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）です。セマンティック検索はオプションの追加機能です。

• 2つのトランスポート — 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 エージェント（Claude Desktop、Codex CLI、Cursor、Cline、Continue など）に、あなたが所有するプレーンな Markdown ファイルに保存される永続的で検索可能な長期メモリを提供します。このフレームワークは独自のメモリデータを持ちません。各ユーザーは自分のメモリディレクトリと SQLite インデックスを指定します。

特長

• ファイルネイティブ：メモリは人間が読める Markdown で、ドメイン/日付で整理されています。grep、編集、git でのバージョン管理が可能で、独自形式によるロックインはありません。

• デュアルチャネル検索：SQLite FTS5（trigram トークナイザ、中英語対応）+ オプションのセマンティックベクトル（ローカル bge-small-zh、完全オフライン）を RRF で融合。3文字未満の短いクエリは自動的に LIKE にフォールバックします。

• 監査付き書き込み：エージェントは .md を直接編集せず、write_log に追記し、flush/apply でホワイトリストに従って配布します。各書き込みは追跡可能です。

• 必須依存関係ゼロ：コアは純粋な Python 標準ライブラリ（sqlite3/re/json）。セマンティック検索はオプションの追加機能です。

• 2つのトランスポート：stdio（デスクトップエージェント）と HTTP/SSE（リモート/共有デプロイ）。同じエンジンで同一の動作。

• 完全な CLI：init、index、search、get、list、write、rm、update、history、flush、stats、doctor、domain、backup、restore、prune、export、および2つのサーバー。

• 管理と安全性：削除は .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。