diff --git a/README.md b/README.md
index 06be308..895843b 100644
--- a/README.md
+++ b/README.md
@@ -1,36 +1,37 @@
-# AgentMemory
+
+AgentMemory
+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.
+
+ 
+ 
+ 
+ 
+ 
+ 
+
+English | Русский
-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)
@@ -38,41 +39,39 @@ Start here if you want the fuller explanation:
- [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.
+
+ 
+
-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
+
+## Quick start
### Fastest Safe Evaluation Path
Use the built-in `localjson` provider first.
```powershell
-git clone
+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
@@ -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
+git clone https://github.com/AndrewMoryakov/AgentMemory.git
cd AgentMemory
python3 -m venv .venv
./.venv/bin/python -m pip install --upgrade pip
@@ -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:
@@ -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
@@ -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
@@ -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:
@@ -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
@@ -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).
diff --git a/README.ru.md b/README.ru.md
new file mode 100644
index 0000000..7fefd34
--- /dev/null
+++ b/README.ru.md
@@ -0,0 +1,394 @@
+
+AgentMemory
+Одна общая локальная память для ваших ИИ-инструментов и скриптов — CLI, HTTP API и MCP поверх сменного бэкенда памяти, например mem0.
+
+
+
+
+
+
+
+
+English | Русский
+
+```powershell
+agentmemory configure --provider localjson # API-ключи не нужны
+agentmemory start-api # один локальный рантайм, несколько клиентских интерфейсов
+```
+
+AgentMemory — это общий локальный рантайм памяти для ИИ-клиентов и агентов. Он стоит над бэкендом памяти вроде `mem0` и даёт одну стабильную поверхность через CLI, HTTP API и MCP: то, что сохранил один инструмент, может вспомнить другой. Сейчас это **публичная альфа**; прежде чем на него опираться, прочитайте [Текущий статус](#текущий-статус) и [Текущие ограничения](#текущие-ограничения).
+
+## Зачем нужен AgentMemory?
+
+Большинство систем памяти решают задачу бэкенда: хранить, извлекать и ранжировать воспоминания. AgentMemory решает другую задачу: сделать один бэкенд памяти пригодным как единый локальный рантайм для нескольких клиентских интерфейсов.
+
+- **Если** несколько ИИ-инструментов, скриптов и агентских клиентов должны делить одну память, **то** AgentMemory даёт им одни и те же операции через CLI, локальный HTTP API и MCP.
+- **Если** у вашего бэкенда памяти есть локальные ограничения на процессы или блокировки, **то** один процесс-владелец держит бэкенд, а всё остальное ходит через него.
+- **Если** нужен стабильный контракт поверх особенностей конкретных бэкендов, **то** провайдеры стоят за единым контрактом провайдера с нормализованными записями и типизированными ошибками.
+- **Если** хочется ещё и посмотреть, что именно запомнено, **то** локальный API отдаёт браузерный интерфейс для просмотра и редактирования, а команды `doctor` объясняют, что не так.
+
+Разница в одной строке: `mem0` — это движок памяти; `AgentMemory` — слой рантайма памяти, и он *не* решает, что нужно помнить временно, а что постоянно.
+
+**Для кого это не подходит.** Скорее всего, AgentMemory вам не нужен, если память принадлежит одному Python-приложению, прямая интеграция с провайдером уже чистая, вам не нужен доступ по MCP или HTTP и не нужно, чтобы несколько инструментов делили один рантайм. В этом случае прямая интеграция с `mem0` обычно проще.
+
+Подробнее (документы на английском):
+
+- [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)
+
+Более конкретные сценарии: [Use Cases](docs/USE_CASES.md), [Shared Runtime Demo](examples/shared-runtime-demo.md), [MCP Demo](examples/mcp-demo.md).
+
+## Возможности
+
+- **Один рантайм, три интерфейса** — CLI, локальный HTTP API и MCP работают через одни и те же общие операции.
+- **Сменные провайдеры** — `mem0` (основной семантический путь), `localjson` (встроенный провайдер для тестов и демо), `claude_memory` (консервативный файловый адаптер для поверхностей памяти Claude Code) и `mempalace` (экспериментальный локальный семантический провайдер).
+- **Подключение клиентов** — `connect-clients` автоматически подключает AgentMemory к найденным ИИ-клиентам и редакторам; `status-clients` и `doctor-clients` проверяют результат. Сначала Windows.
+- **Браузерный интерфейс** — обзор рантайма, обозреватель воспоминаний, редактирование, закрепление и удаление, статус клиентов.
+- **Удалённые MCP-коннекторы** — MCP поверх HTTP на `POST /mcp` с OAuth 2.1 и Dynamic Client Registration — для хостируемых клиентов вроде пользовательских коннекторов Claude.ai и ChatGPT.
+- **Встроенная диагностика** — `doctor` проверяет venv, конфигурацию, наличие ключей и состояние; осведомлённые о возможностях подсказки — часть продукта.
+- **Опциональная семантика жизненного цикла** — TTL-истечение, если вызывающая сторона решит им пользоваться.
+- **Сертификация провайдеров** — провайдеры проверяются по единому общему контракту (`provider-certify`).
+
+## Как это работает
+
+
+
+
+
+1. **Выберите провайдера.** `agentmemory configure --provider localjson` (или `mem0`) выбирает бэкенд памяти за рантаймом.
+2. **Запустите один локальный рантайм.** `agentmemory start-api` поднимает общий рантайм; он может владеть процессом бэкенда, так что остальные клиенты ходят через него, а не борются за локальные блокировки.
+3. **Подключите клиентов.** CLI, скрипты по HTTP и MCP-клиенты (через `connect-clients` или [сниппеты](#основные-команды)) обращаются к одному и тому же рантайму.
+4. **Одни и те же операции везде.** Клиенты говорят с общим контрактом, а не с API конкретного бэкенда, поэтому записи одного инструмента видны другим.
+
+
+## Быстрый старт
+
+### Самый безопасный путь для первой проверки
+
+Сначала используйте встроенный провайдер `localjson`.
+
+```powershell
+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
+.\.venv\Scripts\python.exe -m pip install -e .
+.\.venv\Scripts\agentmemory.exe configure --provider localjson
+.\.venv\Scripts\agentmemory.exe doctor
+.\.venv\Scripts\agentmemory.exe start-api
+.\.venv\Scripts\python.exe .\examples\http_python_roundtrip.py
+.\.venv\Scripts\python.exe -m agentmemory.ops_cli list --user-id examples-http-roundtrip --limit 5
+```
+
+Этот путь доказывает, что:
+
+- пакет устанавливается
+- локальный рантайм стартует
+- HTTP API работает
+- один клиентский интерфейс сразу может читать и писать память
+
+Как выглядит успех:
+
+- `doctor` не сообщает блокирующих ошибок
+- `start-api` печатает URL локального API
+- `http_python_roundtrip.py` печатает созданное воспоминание, а также результаты list и search
+- последняя команда `list` показывает хотя бы одно воспоминание для `examples-http-roundtrip`
+
+Когда закончите:
+
+```powershell
+.\.venv\Scripts\agentmemory.exe stop-api
+```
+
+### macOS / Linux
+
+```sh
+git clone https://github.com/AndrewMoryakov/AgentMemory.git
+cd AgentMemory
+python3 -m venv .venv
+./.venv/bin/python -m pip install --upgrade pip
+./.venv/bin/python -m pip install -e .
+./.venv/bin/agentmemory configure --provider localjson
+./.venv/bin/agentmemory doctor
+./.venv/bin/agentmemory start-api
+./.venv/bin/python ./examples/http_python_roundtrip.py
+./.venv/bin/python -m agentmemory.ops_cli list --user-id examples-http-roundtrip --limit 5
+```
+
+Как выглядит успех:
+
+- `doctor` не сообщает блокирующих ошибок
+- `start-api` печатает URL локального API
+- скрипт roundtrip печатает созданное воспоминание, а также результаты list и search
+- последняя команда `list` показывает хотя бы одно воспоминание для `examples-http-roundtrip`
+
+Когда закончите:
+
+```sh
+./.venv/bin/agentmemory stop-api
+```
+
+### Основной семантический бэкенд
+
+Переключайтесь на `mem0` только после того, как путь с `localjson` выше сработал. Если нужен основной семантический путь, переключитесь на `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
+```
+
+Как выглядит успех:
+
+- `doctor` подтверждает, что настроенный рантайм пригоден к работе
+- `start-api` чисто стартует с настроенным провайдером
+- можно снова запустить `.\.venv\Scripts\python.exe .\examples\http_python_roundtrip.py`
+
+### Демо общего рантайма
+
+Канонический сценарий знакомства:
+
+- записать воспоминание через локальный HTTP API
+- прочитать то же воспоминание через CLI
+- убедиться, что оба клиентских интерфейса обслуживает один общий рантайм
+
+См. [Shared Runtime Demo](examples/shared-runtime-demo.md).
+
+### Локальные файлы рантайма
+
+AgentMemory создаёт локальное состояние рантайма при настройке и использовании. Эти файлы только локальные, их не нужно коммитить:
+
+- `.env`
+- `agentmemory.config.json`
+- `data/`
+
+В репозитории лежат только безопасные шаблоны вроде `.env.example`.
+
+### Быстрое устранение неполадок
+
+Если быстрый старт не заработал сразу, проверьте сначала следующее:
+
+- Если `agentmemory` не находится, используйте явные пути к командам в `.venv`, как показано выше, а не полагайтесь на активацию оболочки.
+- Если API не стартует, повторите `.\.venv\Scripts\agentmemory.exe doctor` и сначала прочитайте блокирующие ошибки.
+- Если порт API занят, `start-api` должен выбрать свободный; повторяйте скрипт roundtrip только после того, как напечатан URL API.
+- Если путь с `mem0` не работает, вернитесь к `localjson`. Первый путь проверки не должен зависеть от внешних API-ключей и настройки семантического провайдера.
+
+## Снимок архитектуры
+
+```mermaid
+flowchart TD
+ A["Clients and Tools"] --> B["CLI / HTTP API / MCP / Browser UI"]
+ B --> C["Shared Runtime Layer"]
+ C --> D["Provider Contract"]
+ D --> E["Providers: mem0, localjson, claude_memory, mempalace, future providers"]
+```
+
+Текущие слои рантайма:
+
+- контракт провайдера: нормализованные записи, типизированные ошибки провайдера, возможности (capabilities), политика рантайма
+- общий рантайм: реестр операций, адаптеры, валидация, формирование ошибок, маршрутизация через прокси/напрямую
+- интерфейсы: CLI, HTTP API, MCP, интерактивная оболочка, браузерный интерфейс
+- опциональная семантика рантайма: пагинация, переносимость данных, инвентаризация областей (scope) и управляемая пользователем поддержка жизненного цикла
+
+Подробнее:
+
+- [Architecture](docs/ARCHITECTURE.md)
+- [Provider Adapter Rules](docs/PROVIDER_ADAPTER_RULES.md)
+- [Future Memory Providers](docs/future-memory-providers/README.md)
+
+## Текущий статус
+
+- `public alpha` (публичная альфа)
+- локальный продукт (local-first)
+- ядро рантайма работает на Windows, Linux и ожидаемо на macOS
+- процесс интеграции с клиентами сначала ориентирован на Windows
+- `mem0` — основной семантический провайдер
+- `localjson` — встроенный провайдер для тестов и демо
+- `claude_memory` — консервативный файловый адаптер для поверхностей памяти Claude Code
+- `mempalace` — экспериментальный локальный семантический провайдер на базе коллекции MemPalace, принадлежащей AgentMemory
+- контракт провайдера, реестр операций, транспортные адаптеры и политика рантайма реализованы
+- диагностика и обнаружение областей (scope) входят в текущую поверхность продукта
+
+## Текущие ограничения
+
+AgentMemory пригоден как локальный рантайм общей памяти, но это всё ещё публичная альфа. Актуальный индекс рисков и багов находится в [Backlog — Known Bugs & Hygiene Items](docs/planning/BACKLOG.md).
+
+Важные текущие ограничения:
+
+- TTL существует как опциональная поддержка истечения. Это метаданные, управляемые вызывающей стороной, а не автоматическая классификация на краткосрочную и долгосрочную память. Провайдерам с нарушенной синхронизацией реестра областей может потребоваться `rebuild-scope-registry`, прежде чем TTL-очистку можно считать полной.
+- `mem0` использует безопасный откат к одной странице для пагинации, пока не реализована безопасная для бэкенда стратегия курсоров.
+- Дрейф внешней сети в Compose v2 смягчается скриптом `deploy/redeploy.sh`, но первопричина остаётся вне этого репозитория.
+
+## Ключевое проектное решение для Mem0
+
+`mem0` в этом проекте использует локальное встроенное хранилище, а у локальных встроенных бэкендов бывают ограничения на процессы и блокировки.
+
+AgentMemory решает это, давая провайдеру явную транспортную политику рантайма:
+
+- процесс локального API может владеть рантаймом бэкенда
+- остальные клиенты могут ходить через этот рантайм
+- общим слоям не нужны ветвления под конкретный бэкенд для транспортного поведения
+
+Это один из самых наглядных примеров того, зачем нужен слой рантайма памяти, даже когда бэкенд по-прежнему `mem0`.
+
+## Основные команды
+
+```powershell
+.\.venv\Scripts\agentmemory.exe --help
+.\.venv\Scripts\agentmemory.exe doctor
+.\.venv\Scripts\agentmemory.exe configure --provider localjson
+.\.venv\Scripts\agentmemory.exe configure --provider mem0 --openrouter-api-key "your-openrouter-key"
+.\.venv\Scripts\agentmemory.exe start-api
+.\.venv\Scripts\agentmemory.exe stop-api
+.\.venv\Scripts\agentmemory.exe mcp-smoke
+.\.venv\Scripts\agentmemory.exe connect-clients
+.\.venv\Scripts\agentmemory.exe status-clients --compact
+.\.venv\Scripts\agentmemory.exe doctor-clients --compact
+```
+
+`agentmemory snippets` печатает готовые сниппеты для Claude Code и Gemini CLI.
+
+## Точки входа в корне репозитория
+
+Для тех, кому нужен один очевидный запуск из корня репозитория, AgentMemory также поставляет тонкие обёртки для Windows и POSIX-оболочек.
+
+Windows:
+
+```powershell
+.\agentmemory.ps1 doctor
+.\start-agentmemory-api.ps1
+.\stop-agentmemory-api.ps1
+.\agentmemory-mcp.ps1
+```
+
+macOS / Linux:
+
+```sh
+./agentmemory.sh doctor
+./start-agentmemory-api.sh
+./stop-agentmemory-api.sh
+./agentmemory-mcp.sh
+```
+
+Эти обёртки делегируют работу поддерживаемым скриптам в `scripts/`, так что корень остаётся удобным, а операционная реализация не уезжает из `scripts/`.
+
+## Удалённые MCP-коннекторы (Claude.ai, ChatGPT)
+
+Когда AgentMemory опубликован по публичному URL, он говорит по MCP поверх HTTP на `POST /mcp` и поддерживает OAuth 2.1 с Dynamic Client Registration (RFC 7591). Хостируемые MCP-клиенты вроде Custom Connectors в Claude.ai или ChatGPT находят сервер и регистрируются сами, без выданного оператором client_id.
+
+Настройка в Claude.ai:
+
+1. Settings → Connectors → **Add custom connector**.
+2. **Remote MCP server URL**: `https://your-host/mcp`.
+3. Сохраните. Claude.ai запрашивает `/.well-known/oauth-authorization-server`, делает POST на `/register`, чтобы получить собственные учётные данные клиента, открывает страницу авторизации и сохраняет полученный токен доступа.
+
+Поля в разделе «Advanced» заполнять не нужно. Записи клиентов хранятся в `{runtime_dir}/oauth_clients.json`, выданные токены — в `{runtime_dir}/oauth_tokens.json`; оба файла переживают перезапуск контейнера.
+
+Серверные настройки:
+
+- `AGENTMEMORY_API_TOKEN` — заранее выданный bearer-токен, принимается наряду с OAuth.
+- `AGENTMEMORY_OAUTH_CLIENT_ID` / `_SECRET` — необязательный статический клиент. Не нужен, пока включён DCR (по умолчанию).
+- `AGENTMEMORY_OAUTH_DISABLE_DCR=1` — отключить `/register` (тогда клиенты должны быть выданы заранее).
+- `AGENTMEMORY_REGISTER_RATE_LIMIT_PER_HOUR` — лимит на IP для /register (по умолчанию 20).
+- `AGENTMEMORY_PUBLIC_URL` — канонический https-URL, который сервер должен сообщать в OAuth discovery.
+
+## Браузерный интерфейс
+
+Локальный API также отдаёт браузерный интерфейс по адресу:
+
+```text
+http://127.0.0.1:8765/
+```
+
+Текущие возможности браузерного интерфейса:
+
+- обзор рантайма
+- обозреватель воспоминаний
+- просмотр деталей воспоминания
+- редактирование текста и метаданных воспоминания
+- закрепление важных воспоминаний
+- удаление малоценных воспоминаний
+- сводка по статусу клиентов
+
+## Провайдеры
+
+### Mem0
+
+Используйте `mem0`, когда нужны:
+
+- семантический поиск
+- извлечение и эмбеддинги через OpenRouter
+- основной продакшен-путь этого репозитория
+
+Примечания:
+
+- требуется `OPENROUTER_API_KEY`
+- в этом репозитории использует транспорт через прокси процесса-владельца
+- является текущим провайдером по умолчанию
+
+### Local JSON
+
+Используйте `localjson`, когда нужны:
+
+- ноль внешних API-зависимостей
+- простой встроенный бэкенд для тестов и демо
+- провайдер, который можно просмотреть на диске
+
+## Карта документации
+
+- [Start Here](docs/START_HERE.md)
+- [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)
+- [Use Cases](docs/USE_CASES.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Runtime Boundaries](docs/RUNTIME_BOUNDARIES.md)
+- [Backlog / Current Limitations](docs/planning/BACKLOG.md)
+- [Positioning Assets](docs/POSITIONING.md)
+- [Roadmap](docs/planning/ROADMAP.md)
+- [Contributing](CONTRIBUTING.md)
+- [Security](SECURITY.md)
+- [Support](SUPPORT.md)
+
+## Примеры
+
+- [HTTP Python Roundtrip](examples/http_python_roundtrip.py)
+- [Shared Runtime Demo](examples/shared-runtime-demo.md)
+- [MCP Demo](examples/mcp-demo.md)
+
+## Проверка
+
+Полезные локальные проверки:
+
+```powershell
+.\.venv\Scripts\python.exe -m unittest discover -s tests -v
+.\.venv\Scripts\python.exe -m compileall agentmemory tests scripts/mcp-smoke-test.py
+.\.venv\Scripts\agentmemory.exe mcp-smoke
+.\.venv\Scripts\python.exe -m agentmemory.ops_cli list-scopes --limit 20
+```
+
+## Сертификация провайдеров
+
+AgentMemory рассматривает провайдеры как адаптерные слои за одним общим контрактом.
+
+Полезные ссылки:
+
+- [PROVIDER_CERTIFICATION.md](docs/PROVIDER_CERTIFICATION.md)
+- [tests/provider_contract_harness.py](tests/provider_contract_harness.py)
+
+Быстрые вспомогательные команды:
+
+```powershell
+.\.venv\Scripts\provider-certify.exe --list
+.\.venv\Scripts\provider-certify.exe --list --json
+.\.venv\Scripts\provider-certify.exe localjson
+.\.venv\Scripts\provider-certify.exe localjson --json --run-tests --summary-only
+```
+
+## Лицензия
+
+[MIT](LICENSE).
diff --git a/docs/assets/AgentMemory-hero.png b/docs/assets/AgentMemory-hero.png
new file mode 100644
index 0000000..597f052
Binary files /dev/null and b/docs/assets/AgentMemory-hero.png differ
diff --git a/docs/assets/AgentMemory-how-it-works.png b/docs/assets/AgentMemory-how-it-works.png
new file mode 100644
index 0000000..78c7a30
Binary files /dev/null and b/docs/assets/AgentMemory-how-it-works.png differ