mcp-memory

MCP Memory Server

Общий API к markdown-памяти для OpenClaw, Codex, Claude Code и любых других MCP-клиентов. Один файл src/server.py — JSON-RPC по stdio; зависимости — Python ≥ 3.10, git, ripgrep (fallback — grep).

Source of truth — markdown в git: MEMORY.md, memory/, wiki/. Сервер — тонкий слой доступа с ACL по identity клиента; собственного состояния и индексов у него нет.

Быстрый старт

python3 -m pip install --user mcp-memory

# Корень рабочей памяти (MEMORY.md, memory/, wiki/); по умолчанию — текущая директория
export MCP_MEMORY_ROOT="$HOME/my-agent-workspace"

# Identity клиента обязательна: openclaw | claude | codex | external:<name>
MCP_MEMORY_CLIENT_ID=claude mcp-memory

Ручная проверка:

printf '%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"memory_status","arguments":{}}}' \
  | MCP_MEMORY_CLIENT_ID=claude mcp-memory

Identity

MCP_MEMORY_CLIENT_ID задаёт identity клиента и его права. Без пина или с неизвестным значением сервер завершается с кодом 2. Параметр client_id в tool-call не принимается (отбрасывается) — identity нельзя самопровозгласить. Identity определяет тот, кто запустил сервер, а не модель: OpenClaw поверх Codex или Claude runtime остаётся openclaw.

Установка как MCP-сервер

Claude Code

.mcp.json в корне проекта (см. examples/claude-code.mcp.json) или

claude mcp add memory -e MCP_MEMORY_ROOT=/path/to/your/workspace -e MCP_MEMORY_CLIENT_ID=claude -- mcp-memory

Codex

Фрагмент ~/.codex/config.toml — examples/codex-config.toml:

[mcp_servers.memory]
command = "mcp-memory"

[mcp_servers.memory.env]
MCP_MEMORY_ROOT = "/path/to/your/workspace"
MCP_MEMORY_CLIENT_ID = "codex"

OpenClaw

В конфиге gateway — mcp.servers.memory с command: mcp-memory и env.MCP_MEMORY_CLIENT_ID=openclaw.

Tools

Tool	Что делает
memory_search(query, corpus, maxResults)	ripgrep по MEMORY.md + memory/ (свежие дневники первыми) и wiki/**/*.md. corpus: all (по умолчанию; результаты корпусов чередуются), memory, wiki. Claims со статусом superseded/archived скрыты
memory_get(path, from, lines)	Чтение файла в пределах memory/wiki root; traversal и секреты (.env*, *.session*, secrets*.json) блокируются
memory_append(content, metadata)	Запись в daily note клиента <namespace>/YYYY-MM-DD.md; metadata (source_trust, topic, session, observed_at, source_refs) пишется в заголовок записи
wiki_get(slug)	Страница по slug: syntheses/ → корень wiki → inbox клиента
wiki_update(slug, content, claims, title, heading, create)	Human note и/или structured claims во frontmatter; коммитится только страница
memory_propose_update(target, content, rationale, metadata)	Proposal в wiki/inbox/<client>/proposals/; guard: already_in_wiki, duplicate, rejected (несуществующая цель без metadata.new_page=true); metadata.force=true обходит
memory_status()	Identity, корни, write-каталоги, daily-файл, masterWrite

Semantic search в сервере нет намеренно: векторный индекс не является source of truth, а у OpenClaw он есть нативно. Пересборку wiki сервер не запускает — это задача внешнего планировщика.

Namespace и права

Identity	Daily notes	Wiki
openclaw	memory/YYYY-MM-DD.md — общий дневник	вся wiki/ (куратор)
claude	memory/claude/	wiki/inbox/claude/
codex	memory/codex/	wiki/inbox/codex/
external:<name>	memory/external/<name>/	wiki/inbox/external/<name>/

Master-память — MEMORY.md и wiki/syntheses/. Её меняет только openclaw (напрямую или через wiki_update); остальные — через proposal flow. Для openclaw сервер блокирует memory_propose_update на master-цели: куратор применяет изменения сам.

Proposal flow

1. Клиент вызывает memory_propose_update(target, content, rationale, metadata); файл — wiki/inbox/<client>/proposals/YYYY-MM-DD-HHMMSS-<slug>.md со статусом pending.
2. Guard отсекает шум до записи: факт уже на странице (already_in_wiki), такой proposal уже есть (duplicate), цели нет (rejected); отказы — в wiki/inbox/<client>/rejected-proposals.jsonl.
3. Куратор (openclaw или человек) применяет или отклоняет proposal и ставит статус в файле: applied, already_applied, superseded, duplicate, rejected.

Конфигурация

config/server.json (или файл из MCP_MEMORY_CONFIG): memoryRoot, wikiRoot, gitRepo, namespaces — для каждой identity список write-каталогов (первый — daily notes); external — шаблон, к каталогам добавляется <name>. Относительные пути считаются от MCP_MEMORY_ROOT (по умолчанию — текущая директория); MCP_MEMORY_WIKI_ROOT и MCP_MEMORY_GIT_REPO переопределяют wiki и git-репозиторий.

Безопасность

• Identity — только из env-пина; client_id из запроса отбрасывается.
• Чтение и запись — через Path.resolve().relative_to(): .., абсолютные пути вне root и symlink-выходы блокируются.
• Запись под fcntl exclusive lock; после записи — git commit только затронутого файла (если репозиторий инициализирован).
• Proposal с source_trust=external, сформулированный как инструкция, правило поведения или правка MEMORY.md, отклоняется — защита от отравления памяти.
• Claims сохраняют provenance (source_refs, observed_at).
• Секреты в память не пишутся — только имена env-переменных или ссылки на секрет-хранилище.
• Диагностика — в stderr; stdout — только JSON-RPC.

Тесты

python3 -m unittest discover -s tests -v

Структура

mcp-memory/
  src/server.py           ← сервер (stdio JSON-RPC, 7 tools)
  config/server.json      ← корни и namespaces по умолчанию
  examples/
    ADD_CLIENT.md         ← как подключить нового клиента
    claude-code.mcp.json  ← пример .mcp.json для Claude Code
    codex-config.toml     ← пример для ~/.codex/config.toml
  tests/                  ← unittest

История изменений — CHANGELOG.md.