memory-mcp-openmemkit

Файловый, двухканальный поиск по памяти ИИ-агента в виде MCP-сервера. / 文件原生、双通道检索的 AI 记忆 MCP 服务器。

English | 中文

English

openmemkit предоставляет любому MCP-совместимому ИИ-агенту (Claude Desktop, Codex CLI, Cursor, Cline, Continue, …) постоянную, запрашиваемую память, которая хранится в обычных Markdown-файлах, которыми вы владеете. Фреймворк не содержит собственных данных памяти — каждый пользователь указывает ему свой каталог памяти и индекс SQLite.

Почему openmemkit

• Файловый подход — воспоминания представлены в виде читаемого Markdown, организованного по доменам и датам. Их можно искать через grep, редактировать и версионировать с помощью git; никакой проприетарной привязки.

• Двухканальный поиск — SQLite FTS5 (триграммный токенизатор, отлично подходит для CJK и английского) плюс опциональные семантические эмбеддинги (локальные bge-small-zh, офлайн), объединённые с помощью Reciprocal Rank Fusion. Короткие запросы (<3 символов) автоматически переключаются на LIKE.

• Аудируемые записи — агенты никогда не редактируют .md напрямую. Они добавляют записи в write_log; явный шаг flush/apply распределяет записи согласно настраиваемому белому списку. Каждая запись отслеживается.

• Ноль обязательных зависимостей — ядро использует только стандартную библиотеку Python (sqlite3, re, json). Семантический поиск — опциональное дополнение.

• Два транспорта — stdio (для настольных агентов) и HTTP/SSE (для удалённых/общих развёртываний), один и тот же движок, идентичное поведение.

• Готовый CLI — init, index, search, get, write, flush, stats, doctor, domain и оба сервера.

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

pip install memory-mcp-openmemkit

# 1. Create your OWN empty memory root (the framework ships no data)
openmemkit init

# 2. Point your agent at it (stdio), then ask it to remember things
openmemkit serve

Расположение по умолчанию (переопределяется флагами, переменными окружения или TOML-конфигом):

Конфигурация MCP-клиента

stdio (Claude Desktop claude_desktop_config.json, Codex config.toml и т.д.):

{
  "mcpServers": {
    "openmemkit": {
      "command": "openmemkit",
      "args": ["serve", "--root", "/path/to/your/memories", "--db", "/path/to/index.sqlite"]
    }
  }
}

HTTP/SSE:

openmemkit serve-http --host 127.0.0.1 --port 8765
# SSE endpoint : http://127.0.0.1:8765/sse
# messages POST: http://127.0.0.1:8765/messages/<session>

Инструменты MCP

Семантический поиск (опционально)

pip install "memory-mcp-openmemkit[semantic]"

Затем включите его через конфиг ([semantic] enabled = true), переменную окружения (OPENMEMKIT_SEMANTIC=1) или --semantic при индексации. Модель по умолчанию (BAAI/bge-small-zh-v1.5) загружается с HuggingFace при первом использовании и затем работает полностью офлайн. Можно подключить любой бэкенд, реализовав протокол Embedder и вызвав openmemkit.embedder.register_backend().

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

# openmemkit.toml
root = "~/.local/share/openmemkit/memories"
db_path = "~/.local/share/openmemkit/openmemkit.sqlite"

[search]
default_top_k = 60
default_mode = "hybrid"      # keyword | hybrid | vector
min_fts_len = 3

[semantic]
enabled = false              # flip to true after installing [semantic]
model = "BAAI/bge-small-zh-v1.5"

[write]
auto_apply_kinds = ["network_fetch", "task_history", "data_read", "data_written", "memory_note"]
top_level_files = ["MEMORY.md"]

[server]
host = "127.0.0.1"
port = 8765

Порядок разрешения: флаги CLI > переменные окружения OPENMEMKIT_* > TOML > встроенные значения по умолчанию.

CLI

openmemkit init [--force]                       # scaffold an empty memory root
openmemkit index [--semantic] [--incremental]   # (re)build the search index
openmemkit search "query" [--domain web] [--mode hybrid]
openmemkit get notes/project.md
openmemkit list [--domain notes]
openmemkit write --kind memory_note --summary "..."
openmemkit rm notes/old.md [--summary "..."]    # delete (moves to .trash/)
openmemkit update notes/x.md --file new.md      # replace (archives old version)
openmemkit history [notes/x.md] [--json]        # audited change trail
openmemkit flush                                # apply pending writes + reindex
openmemkit stats [--json]
openmemkit doctor [--fix]                       # integrity + index-drift check
openmemkit domain list|add|rm <name> [--force]
openmemkit backup [--output out.tar.gz]         # snapshot memories + SQLite
openmemkit restore backup.tar.gz --yes          # restore (moves current aside)
openmemkit prune --domain web --days 90 [--delete] [--dry-run]
openmemkit export --format jsonl|md [--out f]   # bulk export
openmemkit serve                                # MCP stdio
openmemkit serve-http --host 127.0.0.1 --port 8765

Управление и безопасность данных

• Удаление обратимо. memory_delete / rm перемещают файлы в .trash/YYYY-MM-DD/ и записывают запись tombstone; ничего не удаляется безвозвратно.

• Обновления версионируются. memory_update / update копируют предыдущий файл в .archive/YYYY-MM-DD/ и связывают записи журнала через parent_id, поэтому history показывает полную цепочку.

• Резервное копирование/восстановление. backup создаёт tar.gz вашего дерева memories/ плюс согласованный снимок SQLite через VACUUM INTO (с manifest.json); restore откладывает текущее состояние перед заменой, так что операция обратима.

• Хранение. prune архивирует (или с --delete безвозвратно удаляет) файлы старше retention_days для каждого домена, с --dry-run для предпросмотра.

• MEMORY.md защищён от удаления/обновления через движок.

Модель безопасности

• Агенты пишут только через memory_write → write_log; они не могут трогать произвольные файлы. Обход пути отклоняется при чтении.

• Автоприменение основано на белом списке. Типы вне белого списка остаются pending до проверки (CLI flush применяет настроенные автоматические типы).

• OPENMEMKIT_READONLY=1 отключает все записи — полезно для совместного использования одного корня памяти несколькими агентами.

• Движок читает только внутри настроенного root и пишет в db_path. Нет телеметрии и сетевых вызовов, кроме опциональной загрузки модели.

Разработка

git clone <repo> && cd memory-mcp-openmemkit
uv sync --extra dev
uv run pytest                      # 28 tests: chunker/search/write/CLI/stdio/HTTP
uv run openmemkit --version

Лицензия

MIT.

Related MCP server: mcp-ltm

中文

openmemkit 为任何兼容 MCP 的 AI agent（Claude Desktop、Codex CLI、Cursor、Cline、 Continue 等）提供持久、可检索的长期记忆，记忆以你拥有的纯 Markdown 文件形式存储。 框架本身不携带任何记忆数据——每个用户都把它指向自己的记忆目录和 SQLite 索引。

特性

• 文件原生：记忆是人类可读的 Markdown，按域/日期组织，可 grep、可编辑、可 git 版本管理，无私有格式锁定。

• 双通道检索：SQLite FTS5（trigram 分词，中英文通吃）+ 可选语义向量（本地 bge-small-zh，完全离线），用 RRF 融合；<3 字短查询自动走 LIKE 兜底。

• 审计式写入：agent 不直接改 .md，先写 write_log，经 flush/apply 按白名单 分发，每条写入可追溯。

• 零强制依赖：核心纯 Python 标准库（sqlite3/re/json），语义检索为可选 extras。

• 双 transport：stdio（桌面 agent）与 HTTP/SSE（远程/共享部署），同一引擎、行为一致。

• 完整 CLI：init、index、search、get、list、write、rm、update、 history、flush、stats、doctor、domain、backup、restore、prune、export， 以及两种 server。

• 管理与安全：删除移入 .trash/（可恢复），更新归档旧版本到 .archive/（版本链）， 备份/恢复带清单，prune 按域保留期归档，MEMORY.md 受保护。

快速开始

pip install memory-mcp-openmemkit

# 1. 创建属于你自己的空记忆库（框架不携带任何数据）
openmemkit init

# 2. 让 agent 以 stdio 方式接入
openmemkit serve

默认路径（可用参数、环境变量或 TOML 配置覆盖）：

客户端配置

stdio（Claude Desktop / Codex 等）：

{
  "mcpServers": {
    "openmemkit": {
      "command": "openmemkit",
      "args": ["serve", "--root", "/你的/记忆目录", "--db", "/你的/index.sqlite"]
    }
  }
}

HTTP/SSE：

openmemkit serve-http --host 127.0.0.1 --port 8765
# SSE：http://127.0.0.1:8765/sse
# 消息 POST：http://127.0.0.1:8765/messages/<session>

语义检索（可选）

pip install "memory-mcp-openmemkit[semantic]"

在配置中开启 [semantic] enabled = true，或设 OPENMEMKIT_SEMANTIC=1，或索引用 --semantic。默认模型 BAAI/bge-small-zh-v1.5 首次使用时从 HuggingFace 下载，之后完全 离线。实现 Embedder 协议并调用 register_backend() 即可接入任意向量后端。

开发

git clone <repo> && cd memory-mcp-openmemkit
uv sync --extra dev
uv run pytest

许可证

MIT。