memory-mcp-openmemkit

파일 네이티브, 이중 채널 검색 AI 에이전트 메모리 MCP 서버. / 文件原生、双通道检索的 AI 记忆 MCP 服务器。

한국어 | 中文

한국어

openmemkit은(는) 모든 MCP 호환 AI 에이전트(Claude Desktop, Codex CLI, Cursor, Cline, Continue 등)에게 사용자가 소유한 일반 Markdown 파일에 저장되는 영구적이고 검색 가능한 메모리를 제공합니다. 프레임워크는 자체 메모리 데이터를 포함하지 않습니다 — 각 사용자는 자신의 메모리 디렉토리와 SQLite 인덱스를 가리키도록 설정합니다.

openmemkit을 사용하는 이유

• 파일 네이티브 — 메모리는 도메인과 날짜별로 구성된 사람이 읽을 수 있는 Markdown입니다. grep, 편집, git으로 버전 관리가 가능하며 독점적인 잠금이 없습니다.

• 이중 채널 검색 — SQLite FTS5(trigram 토크나이저, 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은 memories/ 트리의 tar.gz와 일관된 VACUUM INTO SQLite 스냅샷(manifest.json 포함)을 생성합니다. restore는 교체 전에 현재 상태를 옆으로 이동하므로 되돌릴 수 있습니다.

• 보존. prune은 도메인별 retention_days보다 오래된 파일을 보관하거나 (--delete로 하드 삭제) --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。