memory-mcp-openmemkit

Dateinative, zweikanalige KI-Agenten-Speicherung als MCP-Server. / 文件原生、双通道检索的 AI 记忆 MCP 服务器。

English | 中文

English

openmemkit gibt jedem MCP-kompatiblen KI-Agenten (Claude Desktop, Codex CLI, Cursor, Cline, Continue, …) einen persistenten, abfragbaren Speicher, der in einfachen Markdown-Dateien lebt, die Ihnen gehören. Das Framework wird ohne eigene Speicherdaten ausgeliefert – jeder Benutzer zeigt es auf sein eigenes Speicherverzeichnis und SQLite-Index.

Warum openmemkit

• Dateinativ – Erinnerungen sind menschenlesbares Markdown, organisiert nach Domäne und Datum. grep, bearbeiten und mit git versionieren; keine proprietäre Bindung.

• Zweikanal-Suche – SQLite FTS5 (Trigramm-Tokenizer, ideal für CJK und Englisch) plus optionale semantische Einbettungen (lokal bge-small-zh, offline), fusioniert mit Reciprocal Rank Fusion. Kurze Abfragen (<3 Zeichen) fallen automatisch auf LIKE zurück.

• Auditierte Schreibvorgänge – Agenten bearbeiten .md nie direkt. Sie hängen an ein write_log an; ein expliziter flush/apply-Schritt verteilt Einträge gemäß einer konfigurierbaren Whitelist. Jeder Schreibvorgang ist nachvollziehbar.

• Null Pflichtabhängigkeiten – der Kern ist reine Python-Standardbibliothek (sqlite3, re, json). Semantische Suche ist ein optionales Extra.

• Zwei Transports – stdio (für Desktop-Agenten) und HTTP/SSE (für entfernte/geteilte Bereitstellungen), gleiche Engine, identisches Verhalten.

• CLI mit allem Drum und Dran – init, index, search, get, write, flush, stats, doctor, domain und beide Server.

Schnellstart

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

Standardpfade (überschreibbar mit Flags, Umgebungsvariablen oder einer TOML-Konfiguration):

MCP-Client-Konfiguration

stdio (Claude Desktop claude_desktop_config.json, Codex config.toml usw.):

{
  "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-Tools

Semantische Suche (optional)

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

Aktivieren Sie es dann über die Konfiguration ([semantic] enabled = true), die Umgebungsvariable (OPENMEMKIT_SEMANTIC=1) oder --semantic beim Indizieren. Das Standardmodell (BAAI/bge-small-zh-v1.5) wird bei der ersten Verwendung von HuggingFace heruntergeladen und läuft danach vollständig offline. Tauschen Sie ein beliebiges Backend ein, indem Sie das Embedder-Protokoll implementieren und openmemkit.embedder.register_backend() aufrufen.

Konfiguration

# 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

Auflösungsreihenfolge: CLI-Flags > OPENMEMKIT_*-Umgebungsvariablen > TOML > integrierte Standardwerte.

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

Verwaltung & Datensicherheit

• Löschungen sind wiederherstellbar. memory_delete / rm verschieben Dateien nach .trash/YYYY-MM-DD/ und schreiben einen tombstone-Datensatz; nichts wird endgültig gelöscht.

• Aktualisierungen sind versioniert. memory_update / update kopieren die vorherige Datei nach .archive/YYYY-MM-DD/ und verknüpfen Log-Einträge über parent_id, sodass history die vollständige Kette zeigt.

• Backup/Wiederherstellung. backup erzeugt ein tar.gz Ihres memories/-Baums plus einen konsistenten VACUUM INTO-SQLite-Snapshot (mit einer manifest.json); restore legt den aktuellen Zustand beiseite, bevor er ersetzt wird, sodass er umkehrbar ist.

• Aufbewahrung. prune archiviert (oder löscht mit --delete endgültig) Dateien, die älter als die domänenspezifischen retention_days sind, mit --dry-run zur Vorschau.

• MEMORY.md ist über die Engine vor Löschen/Aktualisieren geschützt.

Sicherheitsmodell

• Agenten schreiben nur über memory_write → write_log; sie können keine beliebigen Dateien anfassen. Pfad-Traversal wird beim Lesen abgelehnt.

• Auto-Apply basiert auf einer Whitelist. Arten außerhalb der Whitelist bleiben pending, bis sie überprüft werden (CLI flush wendet konfigurierte Auto-Arten an).

• OPENMEMKIT_READONLY=1 deaktiviert alle Schreibvorgänge – nützlich, um einen Speicherstamm über mehrere Agenten zu teilen.

• Die Engine liest nur unterhalb des konfigurierten root und schreibt in db_path. Es gibt keine Telemetrie und keinen Netzwerkaufruf außer dem optionalen Modell-Download.

Entwicklung

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

Lizenz

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。