memory-mcp-openmemkit

File-native, dual-channel AI agent memory as an MCP server. / 文件原生、双通道检索的 AI 记忆 MCP 服务器。

English | 中文

---

English

openmemkit gives any MCP-compatible AI agent (Claude Desktop, Codex CLI, Cursor, Cline, Continue, …) a persistent, queryable memory that lives in plain Markdown files you own. The framework ships with no memory data of its own — every user points it at their own memory directory and SQLite index.

Why openmemkit

• File-native — memories are human-readable Markdown organised by domain and date. grep, edit, and version-control them with git; no proprietary lock-in.
• Dual-channel search — SQLite FTS5 (trigram tokenizer, great for CJK and English) plus optional semantic embeddings (local bge-small-zh, offline), fused with Reciprocal Rank Fusion. Short queries (<3 chars) auto-fall-back to LIKE.
• Audited writes — agents never edit .md directly. They append to a write_log; an explicit flush/apply step distributes entries according to a configurable whitelist. Every write is traceable.
• Zero mandatory dependencies — the core is pure Python standard library (sqlite3, re, json). Semantic search is an optional extra.
• Two transports — stdio (for desktop agents) and HTTP/SSE (for remote/shared deployments), same engine, identical behavior.
• Batteries-included CLI — init, index, search, get, write, flush, stats, doctor, domain, and both servers.

Quick start

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

Default locations (override with flags, env vars, or a TOML config):

What	Default
Memory root	~/.local/share/openmemkit/memories
SQLite index	~/.local/share/openmemkit/openmemkit.sqlite
Config file	--config / $OPENMEMKIT_CONFIG

MCP client configuration

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

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

Tool	Purpose
memory_bootstrap	Load MEMORY.md rules + all domain indexes + semantic status (call once at start)
memory_domains	List domains with file counts
memory_search	Search chunks; modes keyword / hybrid (default) / vector; filters by domain/date
memory_get	Read one .md file by path
memory_list	List indexed files with chunk counts/mtime
memory_stats	Index statistics, domain distribution, write-log status, semantic coverage
memory_write	Append an audited entry (task_history/data_read/data_written/network_fetch/memory_note)
memory_update	Replace a .md file's content; old version archived under .archive/, change logged
memory_delete	Move a .md file to .trash/ (recoverable) with a tombstone audit record
memory_history	Show the audited change trail for a path (or the whole write log)
memory_flush	Distribute pending write-log entries to .md, then reindex

Semantic search (optional)

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

Then enable it via config ([semantic] enabled = true), env (OPENMEMKIT_SEMANTIC=1), or --semantic on indexing. The default model (BAAI/bge-small-zh-v1.5) downloads from HuggingFace on first use and runs fully offline afterward. Swap in any backend by implementing the Embedder protocol and calling openmemkit.embedder.register_backend().

Configuration

# 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

Resolution order: CLI flags > OPENMEMKIT_* env vars > TOML > built-in defaults.

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

Management & data safety

• Deletes are recoverable. memory_delete / rm move files to .trash/YYYY-MM-DD/ and write a tombstone record; nothing is hard-deleted.
• Updates are versioned. memory_update / update copy the previous file to .archive/YYYY-MM-DD/ and link log entries via parent_id, so history shows the full chain.
• Backup/restore. backup produces a tar.gz of your memories/ tree plus a consistent VACUUM INTO SQLite snapshot (with a manifest.json); restore moves the current state aside before replacing it, so it is reversible.
• Retention. prune archives (or with --delete hard-deletes) files older than per-domain retention_days, with --dry-run to preview.
• MEMORY.md is protected from delete/update through the engine.

Security model

• Agents only write through memory_write → write_log; they cannot touch arbitrary files. Path traversal is rejected at read time.
• Auto-apply is whitelist-based. Kinds outside the whitelist stay pending until reviewed (CLI flush applies configured auto-kinds).
• OPENMEMKIT_READONLY=1 disables all writes — useful for sharing one memory root across multiple agents.
• The engine only reads beneath the configured root and writes to db_path. There is no telemetry and no network call other than the optional model download.

Development

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

License

MIT.

---

中文

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 配置覆盖）：

项目	默认
记忆根目录	~/.local/share/openmemkit/memories
SQLite 索引	~/.local/share/openmemkit/openmemkit.sqlite
配置文件	--config / $OPENMEMKIT_CONFIG

客户端配置

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。