Skip to content

docs: redesign front-page README (EN + RU) #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AndrewMoryakov merged 1 commit into from
Sep 30, 2026
Merged

docs: redesign front-page README (EN + RU) #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
204 changes: 92 additions & 112 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,78 +1,77 @@
# AgentMemory
<p align="center"><img src="docs/assets/AgentMemory-hero.png" alt="AgentMemory: several AI tool robots and a script read and write notes through one shared memory runtime, with swappable storage behind it" width="100%"></p>
<h1 align="center">AgentMemory</h1>
<p align="center"><b>One shared local memory runtime for your AI tools and scripts — CLI, HTTP API and MCP on top of a swappable memory backend such as mem0.</b></p>
<p align="center">
<a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-informational.svg"></a>
<a href="pyproject.toml"><img alt="Python 3.11+" src="https://img.shields.io/badge/Python-3.11%2B-3776AB.svg?logo=python&logoColor=white"></a>
<a href="#current-status"><img alt="Status: public alpha" src="https://img.shields.io/badge/status-public%20alpha-orange.svg"></a>
<a href="pyproject.toml"><img alt="Version 0.1.0" src="https://img.shields.io/badge/version-0.1.0-blue.svg"></a>
<a href="#current-status"><img alt="Platform: Windows | Linux | macOS" src="https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg"></a>
<a href="https://github.com/AndrewMoryakov/AgentMemory/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/AndrewMoryakov/AgentMemory/actions/workflows/ci.yml/badge.svg"></a>
</p>
<p align="center"><b>English</b> | <a href="README.ru.md">Русский</a></p>

AgentMemory is a shared local memory runtime for AI clients and agents.

It sits above a memory backend such as `mem0` and exposes one stable surface through CLI, HTTP API, and MCP.

If you only need one Python application talking directly to a memory engine, direct `mem0` integration is often enough.

If memory needs to behave like shared local infrastructure for multiple tools, scripts, and agent clients, that is where AgentMemory adds value.

## Why This Project Exists
```powershell
agentmemory configure --provider localjson # no API keys needed
agentmemory start-api # one local runtime, several client surfaces
```

Most memory systems solve the backend problem: storing, retrieving, and ranking memories.
AgentMemory is a shared local memory runtime for AI clients and agents. It sits above a memory backend such as `mem0` and exposes one stable surface through CLI, HTTP API, and MCP — so what one tool saves, another can recall. It is currently a **public alpha**; see [Current Status](#current-status) and [Current Limitations](#current-limitations) before you depend on it.

AgentMemory solves a different problem: making one memory backend usable as one local runtime across multiple client surfaces.
## Why AgentMemory?

That includes:
Most memory systems solve the backend problem: storing, retrieving, and ranking memories. AgentMemory solves a different one: making one memory backend usable as one local runtime across multiple client surfaces.

- CLI workflows
- local HTTP API access
- MCP tool access
- browser-based inspection
- diagnostics and runtime guidance
- provider-aware transport behavior
- optional lifecycle semantics such as TTL expiry when the caller chooses to use them
- **If** several AI tools, scripts, and agent clients should share one memory, **then** AgentMemory gives them the same operations through CLI, local HTTP API, and MCP.
- **If** your memory backend has local process or lock constraints, **then** one owner process can own the backend and everything else proxies through it.
- **If** you want a stable contract above backend-specific quirks, **then** providers sit behind one provider contract with normalized records and typed errors.
- **If** you also want to look at what was remembered, **then** the local API serves a browser UI for inspection and editing, and `doctor` commands explain what is wrong.

This is the main distinction:
The distinction in one line: `mem0` is a memory engine; `AgentMemory` is a memory runtime layer — and it is *not* the layer that decides what should be remembered temporarily or permanently.

- `mem0` is a memory engine
- `AgentMemory` is a memory runtime layer
- `AgentMemory` is not the layer that decides what should be remembered temporarily or permanently
**Who it is not for.** You probably do not need AgentMemory if one Python application owns memory directly, direct provider integration is already clean, you do not need MCP or HTTP access, and you do not need several tools to share one runtime. In that case, direct `mem0` integration is usually simpler.

Start here if you want the fuller explanation:
Fuller explanations:

- [Why AgentMemory Exists](docs/WHY_AGENTMEMORY.md)
- [Mem0 vs AgentMemory](docs/MEM0_VS_AGENTMEMORY.md)
- [What AgentMemory Adds To Mem0](docs/MEM0_WITH_AGENTMEMORY_VALUE.md)
- [What AgentMemory Actually Adds](docs/WHAT_AGENTMEMORY_ACTUALLY_ADDS.md)
- [Start Here](docs/START_HERE.md)

## When You Probably Do Not Need AgentMemory

You probably do not need AgentMemory if:
More concrete scenarios: [Use Cases](docs/USE_CASES.md), [Shared Runtime Demo](examples/shared-runtime-demo.md), [MCP Demo](examples/mcp-demo.md).

- one Python application owns memory directly
- direct provider integration is already clean
- you do not need MCP or HTTP access
- you do not need several tools to share one runtime
## Features

In that case, direct `mem0` integration is usually simpler.
- **One runtime, three surfaces** — CLI, local HTTP API, and MCP all go through the same shared operations.
- **Swappable providers** — `mem0` (main semantic path), `localjson` (built-in test/demo provider), `claude_memory` (conservative file-backed adapter for Claude Code memory surfaces), and `mempalace` (experimental local semantic provider).
- **Client wiring** — `connect-clients` auto-connects AgentMemory to detected AI clients and editors; `status-clients` and `doctor-clients` check the result. Windows-first.
- **Browser UI** — runtime overview, memory explorer, edit, pin and delete, client status.
- **Remote MCP connectors** — MCP over HTTP at `POST /mcp` with OAuth 2.1 and Dynamic Client Registration, for hosted clients such as Claude.ai and ChatGPT custom connectors.
- **Diagnostics built in** — `doctor` checks venv, config, key availability and health; capability-aware guidance is part of the product surface.
- **Optional lifecycle semantics** — TTL expiry when the caller chooses to use it.
- **Provider certification** — providers are checked against one shared contract (`provider-certify`).

## When AgentMemory Is Useful
## How it works

AgentMemory becomes useful when one memory backend must serve many surfaces consistently.
<p align="center">
<img src="docs/assets/AgentMemory-how-it-works.png" alt="AgentMemory: without it each tool keeps its own separate memory; with it, several clients reach one runtime exposing CLI, HTTP API and MCP over a single memory, with any provider behind it" width="100%">
</p>

Strong current examples:
1. **Pick a provider.** `agentmemory configure --provider localjson` (or `mem0`) selects the memory backend behind the runtime.
2. **Run one local runtime.** `agentmemory start-api` starts the shared runtime; it can own the backend process, so other clients proxy through it instead of fighting over local locks.
3. **Connect your clients.** CLI, scripts over HTTP, and MCP clients (via `connect-clients` or the [snippets](#main-commands)) all talk to that one runtime.
4. **Use the same operations everywhere.** Clients talk to the shared contract, not to backend-specific APIs, so one tool's writes are visible to the others.

- one backend reused by CLI, MCP, scripts, and browser tooling
- one owner process for a backend with local runtime constraints
- one stable contract above backend-specific quirks

More concrete scenarios:

- [Use Cases](docs/USE_CASES.md)
- [Shared Runtime Demo](examples/shared-runtime-demo.md)
- [MCP Demo](examples/mcp-demo.md)

## Quickstart
<a id="quickstart"></a>
## Quick start

### Fastest Safe Evaluation Path

Use the built-in `localjson` provider first.

```powershell
git clone <your-repo-url>
git clone https://github.com/AndrewMoryakov/AgentMemory.git
cd AgentMemory
py -3.13 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
Expand Down Expand Up @@ -104,40 +103,10 @@ When you are done:
.\.venv\Scripts\agentmemory.exe stop-api
```

### Local Runtime Files

AgentMemory generates local runtime state during setup and use.

These files are local-only and should not be committed:

- `.env`
- `agentmemory.config.json`
- `data/`

The repository only ships safe templates such as `.env.example`.

### Main Semantic Backend

Only switch to `mem0` after the `localjson` path above succeeds.

If you want the main semantic path, switch to `mem0`:

```powershell
.\.venv\Scripts\agentmemory.exe configure --provider mem0 --openrouter-api-key "your-openrouter-key"
.\.venv\Scripts\agentmemory.exe doctor
.\.venv\Scripts\agentmemory.exe start-api
```

What success looks like:

- `doctor` confirms the configured runtime is usable
- `start-api` starts cleanly with the configured provider
- you can rerun `.\.venv\Scripts\python.exe .\examples\http_python_roundtrip.py`

### macOS / Linux

```sh
git clone <your-repo-url>
git clone https://github.com/AndrewMoryakov/AgentMemory.git
cd AgentMemory
python3 -m venv .venv
./.venv/bin/python -m pip install --upgrade pip
Expand All @@ -162,6 +131,22 @@ When you are done:
./.venv/bin/agentmemory stop-api
```

### Main Semantic Backend

Only switch to `mem0` after the `localjson` path above succeeds. If you want the main semantic path, switch to `mem0`:

```powershell
.\.venv\Scripts\agentmemory.exe configure --provider mem0 --openrouter-api-key "your-openrouter-key"
.\.venv\Scripts\agentmemory.exe doctor
.\.venv\Scripts\agentmemory.exe start-api
```

What success looks like:

- `doctor` confirms the configured runtime is usable
- `start-api` starts cleanly with the configured provider
- you can rerun `.\.venv\Scripts\python.exe .\examples\http_python_roundtrip.py`

### Shared Runtime Demo

The canonical onboarding story is:
Expand All @@ -170,9 +155,17 @@ The canonical onboarding story is:
- read the same memory back through the CLI
- confirm one shared runtime is serving both client surfaces

See:
See [Shared Runtime Demo](examples/shared-runtime-demo.md).

- [Shared Runtime Demo](examples/shared-runtime-demo.md)
### Local Runtime Files

AgentMemory generates local runtime state during setup and use. These files are local-only and should not be committed:

- `.env`
- `agentmemory.config.json`
- `data/`

The repository only ships safe templates such as `.env.example`.

### Quick Troubleshooting

Expand Down Expand Up @@ -221,20 +214,13 @@ More detail:

## Current Limitations

AgentMemory is usable as a local shared-memory runtime, but it is still a
public alpha. The current risk/bug index lives in
[Backlog — Known Bugs & Hygiene Items](docs/planning/BACKLOG.md).
AgentMemory is usable as a local shared-memory runtime, but it is still a public alpha. The current risk/bug index lives in [Backlog — Known Bugs & Hygiene Items](docs/planning/BACKLOG.md).

Important current limitations:

- TTL exists as optional expiry support. It is caller-controlled metadata, not
automatic short-term/long-term classification. Providers with degraded scope
registry sync may require `rebuild-scope-registry` before TTL sweeps can be
considered complete.
- `mem0` uses the safe single-page fallback for pagination until a backend-safe
cursor strategy is implemented.
- Compose v2 external-network drift is mitigated by `deploy/redeploy.sh`, but
the upstream root cause remains outside this repo.
- TTL exists as optional expiry support. It is caller-controlled metadata, not automatic short-term/long-term classification. Providers with degraded scope registry sync may require `rebuild-scope-registry` before TTL sweeps can be considered complete.
- `mem0` uses the safe single-page fallback for pagination until a backend-safe cursor strategy is implemented.
- Compose v2 external-network drift is mitigated by `deploy/redeploy.sh`, but the upstream root cause remains outside this repo.

## Key Design Choice For Mem0

Expand Down Expand Up @@ -263,9 +249,11 @@ This is one of the clearest examples of why a memory runtime layer can be useful
.\.venv\Scripts\agentmemory.exe doctor-clients --compact
```

`agentmemory snippets` prints ready-to-use Claude Code and Gemini CLI snippets.

## Root Entry Points

For users who want one obvious launcher from the repository root, AgentMemory now also ships thin root wrappers for both Windows and POSIX shells.
For users who want one obvious launcher from the repository root, AgentMemory also ships thin root wrappers for both Windows and POSIX shells.

Windows:

Expand All @@ -289,35 +277,23 @@ These wrappers delegate to the maintained scripts in `scripts/`, so the root sta

## Remote MCP Connectors (Claude.ai, ChatGPT)

When AgentMemory is exposed on a public URL, it speaks MCP over HTTP at
`POST /mcp` and supports OAuth 2.1 with Dynamic Client Registration
(RFC 7591). Hosted MCP clients like Claude.ai Custom Connectors or
ChatGPT Custom Connectors discover the server and register themselves
without any operator-issued client_id.
When AgentMemory is exposed on a public URL, it speaks MCP over HTTP at `POST /mcp` and supports OAuth 2.1 with Dynamic Client Registration (RFC 7591). Hosted MCP clients like Claude.ai Custom Connectors or ChatGPT Custom Connectors discover the server and register themselves without any operator-issued client_id.

Setup on Claude.ai:

1. Settings → Connectors → **Add custom connector**.
2. **Remote MCP server URL**: `https://your-host/mcp`.
3. Save. Claude.ai fetches `/.well-known/oauth-authorization-server`,
POSTs to `/register` to mint its own client credentials, opens the
authorize page, and stores the resulting access token.
3. Save. Claude.ai fetches `/.well-known/oauth-authorization-server`, POSTs to `/register` to mint its own client credentials, opens the authorize page, and stores the resulting access token.

No fields under "Advanced" need to be filled in. Client records persist
at `{runtime_dir}/oauth_clients.json` and issued tokens at
`{runtime_dir}/oauth_tokens.json` — both survive container restarts.
No fields under "Advanced" need to be filled in. Client records persist at `{runtime_dir}/oauth_clients.json` and issued tokens at `{runtime_dir}/oauth_tokens.json` — both survive container restarts.

Server-side knobs:

- `AGENTMEMORY_API_TOKEN` — pre-shared bearer accepted alongside OAuth.
- `AGENTMEMORY_OAUTH_CLIENT_ID` / `_SECRET` — optional static client.
Not required when DCR is on (the default).
- `AGENTMEMORY_OAUTH_DISABLE_DCR=1` — turn off `/register` (clients
must then be pre-shared).
- `AGENTMEMORY_REGISTER_RATE_LIMIT_PER_HOUR` — per-IP cap on /register
(default 20).
- `AGENTMEMORY_PUBLIC_URL` — the canonical https URL the server should
advertise in OAuth discovery.
- `AGENTMEMORY_OAUTH_CLIENT_ID` / `_SECRET` — optional static client. Not required when DCR is on (the default).
- `AGENTMEMORY_OAUTH_DISABLE_DCR=1` — turn off `/register` (clients must then be pre-shared).
- `AGENTMEMORY_REGISTER_RATE_LIMIT_PER_HOUR` — per-IP cap on /register (default 20).
- `AGENTMEMORY_PUBLIC_URL` — the canonical https URL the server should advertise in OAuth discovery.

## Browser UI

Expand Down Expand Up @@ -412,3 +388,7 @@ Quick helper commands:
.\.venv\Scripts\provider-certify.exe localjson
.\.venv\Scripts\provider-certify.exe localjson --json --run-tests --summary-only
```

## License

[MIT](LICENSE).
Loading
Loading