memory-mcp-openmemkit

Memoria de agente de IA nativa de archivos y de doble canal como servidor MCP. / 文件原生、双通道检索的 AI 记忆 MCP 服务器。

Español | 中文

Español

openmemkit proporciona a cualquier agente de IA compatible con MCP (Claude Desktop, Codex CLI, Cursor, Cline, Continue, …) una memoria persistente y consultable que vive en archivos Markdown simples que tú posees. El framework no incluye ningún dato de memoria propio — cada usuario lo apunta a su propio directorio de memoria e índice SQLite.

Por qué openmemkit

• Nativo de archivos — los recuerdos son Markdown legible por humanos organizado por dominio y fecha. Puedes usar grep, editarlos y controlar versiones con git; sin bloqueo propietario.

• Búsqueda de doble canal — SQLite FTS5 (tokenizador trigram, excelente para CJK e inglés) más embeddings semánticos opcionales (local bge-small-zh, sin conexión), fusionados con Reciprocal Rank Fusion. Las consultas cortas (<3 caracteres) recurren automáticamente a LIKE.

• Escrituras auditadas — los agentes nunca editan .md directamente. Añaden a un write_log; un paso explícito de flush/apply distribuye las entradas según una lista blanca configurable. Cada escritura es trazable.

• Cero dependencias obligatorias — el núcleo es biblioteca estándar pura de Python (sqlite3, re, json). La búsqueda semántica es un extra opcional.

• Dos transportes — stdio (para agentes de escritorio) y HTTP/SSE (para despliegues remotos/compartidos), mismo motor, comportamiento idéntico.

• CLI completo — init, index, search, get, write, flush, stats, doctor, domain, y ambos servidores.

Inicio rápido

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

Ubicaciones predeterminadas (se pueden sobrescribir con banderas, variables de entorno o un archivo de configuración TOML):

Configuración del cliente MCP

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>

Herramientas MCP

Búsqueda semántica (opcional)

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

Luego actívala mediante configuración ([semantic] enabled = true), variable de entorno (OPENMEMKIT_SEMANTIC=1), o --semantic al indexar. El modelo predeterminado (BAAI/bge-small-zh-v1.5) se descarga de HuggingFace en el primer uso y luego funciona completamente sin conexión. Cambia a cualquier backend implementando el protocolo Embedder y llamando a openmemkit.embedder.register_backend().

Configuración

# 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

Orden de resolución: banderas de CLI > variables de entorno OPENMEMKIT_* > TOML > valores predeterminados integrados.

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

Gestión y seguridad de datos

• Los borrados son recuperables. memory_delete / rm mueven archivos a .trash/YYYY-MM-DD/ y escriben un registro tombstone; nada se elimina permanentemente.

• Las actualizaciones tienen versiones. memory_update / update copian el archivo anterior a .archive/YYYY-MM-DD/ y enlazan las entradas de registro mediante parent_id, de modo que history muestra la cadena completa.

• Copia de seguridad/restauración. backup produce un tar.gz de tu árbol memories/ más una instantánea SQLite consistente VACUUM INTO (con un manifest.json); restore mueve el estado actual a un lado antes de reemplazarlo, por lo que es reversible.

• Retención. prune archiva (o con --delete elimina permanentemente) archivos más antiguos que retention_days por dominio, con --dry-run para previsualizar.

• MEMORY.md está protegido contra borrado/actualización a través del motor.

Modelo de seguridad

• Los agentes solo escriben a través de memory_write → write_log; no pueden tocar archivos arbitrarios. El path traversal se rechaza al leer.

• La aplicación automática se basa en lista blanca. Los tipos fuera de la lista blanca permanecen pending hasta que se revisen (el CLI flush aplica los tipos automáticos configurados).

• OPENMEMKIT_READONLY=1 desactiva todas las escrituras — útil para compartir una raíz de memoria entre múltiples agentes.

• El motor solo lee debajo de la root configurada y escribe en db_path. No hay telemetría ni llamadas de red aparte de la descarga opcional del modelo.

Desarrollo

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

Licencia

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。