MCP Memory Server

Общий API для памяти OpenClaw, Codex, Claude Code и будущих клиентов.

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

# Установка в пользовательское окружение Python
python3 -m pip install --user mcp-memory

# Корень рабочей памяти; по умолчанию используется текущая директория
export MCP_MEMORY_ROOT="$HOME/my-agent-workspace"

# Запуск сервера в stdio-режиме
MCP_MEMORY_CLIENT_ID=codex mcp-memory

# Тест вручную (в другом терминале)
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | MCP_MEMORY_CLIENT_ID=codex mcp-memory

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

Claude Code

Добавить в .claude/settings.json:

{
  "mcpServers": {
    "memory": {
      "command": "mcp-memory",
      "env": {
        "MCP_MEMORY_ROOT": "/path/to/your/workspace",
        "MCP_MEMORY_CLIENT_ID": "claude"
      }
    }
  }
}

Codex

Добавить в конфиг Codex:

{
  "mcpServers": {
    "memory": {
      "command": "mcp-memory",
      "env": {
        "MCP_MEMORY_ROOT": "/path/to/your/workspace",
        "MCP_MEMORY_CLIENT_ID": "codex"
      }
    }
  }
}

OpenClaw подключает тот же сервер через свой конфиг с MCP_MEMORY_CLIENT_ID=openclaw. Значение из env считается авторитетным: если модель или клиент передаст другой client_id в tool-call, сервер его перезапишет env-пином.

Architecture

• Namespace routing. Identity берётся из MCP_MEMORY_CLIENT_ID, если env-пин задан, и только при его отсутствии — из аргумента client_id. openclaw, claude, codex и external:<name> маршрутизируются в свои daily-note директории и wiki inbox.
• Master file protection. MEMORY.md и wiki/syntheses/ считаются master-памятью. OpenClaw редактирует их напрямую по ACL, а Codex, Claude Code и external-клиенты должны использовать proposal flow через memory_propose_update.
• Path safety. Чтение и запись проходят через Path.resolve(...).relative_to(...), поэтому traversal через .., абсолютные пути вне разрешённых root и symlink-выходы за root блокируются.
• File locking. Записи берут fcntl exclusive lock на целевой файл; перед lock создаётся parent-директория, чтобы новые namespace-пути работали без ручной подготовки.
• Logging. Сервер пишет диагностические сообщения только в stderr через logging. stdout используется только для JSON-RPC responses.

Подключение нового MCP-клиента

1. Добавить identity в config/server.json → allowedClients и namespaces.
2. Запустить сервер с доступом клиенту (stdio или Unix socket).
3. Запинить identity через MCP_MEMORY_CLIENT_ID=<client_id>.
4. Клиент получает доступ в рамках своего namespace.

Пример external-клиента:

{
  "namespaces": {
    "external": {
      "write": ["memory/external/my-agent/", "wiki/inbox/external/my-agent/"],
      "prefix": "external"
    }
  }
}

Запуск сервера для external-клиента должен содержать MCP_MEMORY_CLIENT_ID=external:my-agent. Переданный в запросе client_id оставлен для обратной совместимости, но при наличии env-пина не является авторитетным.

Удалённый доступ

Для подключения рабочей станции:

1. На сервере: запустить сервер в stdio-режиме через MCP-клиент.
2. Для удалённой машины использовать transport, который предоставляет этот клиент (например, SSH), не открывая сервер памяти в публичную сеть.

MCP_MEMORY_ROOT=/path/to/your/workspace mcp-memory

Tools

Tool	Описание
memory_search(query, corpus, maxResults, include_historical)	Поиск через ripgrep; по умолчанию скрывает claims со статусом superseded/archived
memory_get(path, from, lines)	Чтение файла
memory_append(client_id, content, metadata)	Запись в daily note
memory_list(corpus, pattern)	Список файлов
wiki_get(slug)	Чтение wiki-страницы
wiki_update(slug, content, claims, title, heading, client_id, create, refresh)	Создание/обновление wiki-страницы: human note, structured claims и пересборка digest
memory_propose_update(target, content, rationale, metadata)	Proposal для master; metadata.source_trust: user/agent/external
memory_status()	Статус namespace

Namespace-маршрутизация

client_id	Куда пишет
openclaw	memory/openclaw/, wiki/inbox/openclaw/, wiki/syntheses/
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 напрямую (MCP_MEMORY_CLIENT_ID=openclaw), даже если OpenClaw работает поверх Codex runtime
• wiki_update для OpenClaw и других клиентов с явным write-ACL на wiki/syntheses/
• Proposal flow (memory_propose_update) для Codex, Claude Code и external-клиентов

Для client_id=openclaw сервер блокирует memory_propose_update на targets MEMORY.md и wiki/syntheses/*: OpenClaw является master-куратором и должен применять такие изменения напрямую.

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

• Секреты не хранятся в памяти.
• Внешние клиенты пишут только в свой namespace.
• Write-операции используют file lock (fcntl).
• После записи — git commit (если репозиторий инициализирован).
• Provenance: source_trust (user/agent/external) в metadata записей и proposals; proposal с source_trust=external, сформулированный как инструкция или правило поведения, отклоняется — защита от отравления памяти.
• Claims поддерживают поля происхождения source_refs и observed_at, они сохраняются через весь proposal flow.
• memory_search по умолчанию не выдаёт claims со статусом superseded или archived; полная история — через include_historical=true.

Тесты

python3 -m unittest discover -s tests -v

MCP_MEMORY_ROOT задаёт каталог с MEMORY.md и папкой memory/. MCP_MEMORY_WIKI_ROOT (по умолчанию $MCP_MEMORY_ROOT/wiki) и MCP_MEMORY_GIT_REPO при необходимости задают отдельные пути. Для локальной настройки можно передать JSON-файл через MCP_MEMORY_CONFIG.

Структура файлов

mcp-memory/
  src/
    server.py          ← MCP-сервер (Python, stdio)
  config/
    server.json        ← Конфигурация namespace и прав
  examples/
    claude-code.json   ← Пример .claude/settings.json
    codex.json         ← Пример конфига Codex
  README.md