From dda043b0ec9d8d9e5da7fe51fc48791086417a9b Mon Sep 17 00:00:00 2001 From: tanaka takashi Date: Sat, 4 Jul 2026 19:19:00 +0900 Subject: ドキュメント更新 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 205 +++++++++++++++++++++++++++++++++++++++----------------------- 1 file changed, 129 insertions(+), 76 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index bf935e0..e86c8f9 100644 --- a/README.md +++ b/README.md @@ -1,128 +1,181 @@ -# tiny-convmem-mcp +# Tiny ConvMem MCP -LLMの会話メッセージをローカルの追記ログへ保存する、Windows向けC17製MCP -サーバです。書込みと削除はディスクへの同期完了後に成功を返し、プロセス再起動時は -ログまたはsnapshotから状態を復旧します。 +Tiny ConvMem MCPは、LLMとの会話をローカル環境へ保存し、あとから検索・参照できる +MCPサーバーです。 -## 必要環境 +会話メッセージをsession単位で蓄積し、本文やタグから検索したり、関連する前後の会話を +取り出したりできます。データは指定したdirectory内に保存され、外部databaseやnetwork +serviceを必要としません。 + +現行versionはWindows x64をサポートしています。将来的には、Linux対応も想定しています。 + +## 主な特徴 + +- **ローカル完結:** 会話データを指定したdirectoryへ保存 +- **永続的な記憶:** MCP hostやPCを再起動しても保存内容を復元 +- **文脈を含む検索:** 本文、summary、tagを検索し、前後のメッセージやrelationも取得 +- **構造化metadata:** 記憶の種類、tier、importance、tag、summary、relationを保持 +- **安全な更新:** revisionを使った競合検出付きのメッセージ更新 +- **耐障害性:** append-only log、CRC検証、snapshot fallback、書込み完了前のdisk flush +- **バックアップ:** JSONL形式のtransactional importとatomic export +- **軽量な実装:** C17で実装されたstdio MCPサーバー + +## 動作環境 - Windows x64 -- Visual Studio Community 2026（Desktop development with C++） +- Visual Studio Community 2026 + - `Desktop development with C++` workload - CMake 4.3以降 - Git -- vcpkg（PATHから実行可能であること） +- vcpkg（`PATH`から実行可能であること） + +## ビルド -## ビルドとテスト +repositoryをcloneし、submoduleを取得してからbootstrap scriptを実行します。 ```powershell git submodule update --init --recursive -.\scripts\bootstrap.ps1 -Configuration Debug +.\scripts\bootstrap.ps1 -Configuration Release ``` -手動実行する場合は次のとおりです。 +生成される実行ファイル: + +```text +build\windows-vs2026\src\Release\tiny-convmem-mcp.exe +``` + +手動でbuildする場合: ```powershell $config = vcpkg z-print-config | ConvertFrom-Json $env:VCPKG_ROOT = $config.'vcpkg-root' + cmake --preset windows-vs2026 -cmake --build --preset windows-vs2026-debug -ctest --preset windows-vs2026-debug +cmake --build --preset windows-vs2026-release +ctest --preset windows-vs2026-release ``` -AddressSanitizer構成は独立した`build/windows-vs2026-asan`を使用します。 +## MCPクライアントへの登録 -```powershell -cmake --preset windows-vs2026-asan -cmake --build --preset windows-vs2026-asan -ctest --preset windows-vs2026-asan -``` +MCPクライアントのstdio server設定へ、実行ファイルと保存先を登録します。設定形式は +クライアントによって異なりますが、一般的なJSONの例は次のとおりです。 -単体テストにはUTF-8/UTF-16、unaligned binary codec、allocation失敗、short I/Oと -操作別I/O失敗が含まれます。自前関数とテストの対応は -[function coverage map](tests/function-coverage.md)を参照してください。 +```json +{ + "mcpServers": { + "tiny-convmem": { + "command": "C:\\path\\to\\tiny-convmem-mcp.exe", + "args": ["--data-dir", "C:\\path\\to\\conversation-memory"] + } + } +} +``` -## 起動 +`--data-dir`は必須です。相対pathも利用できますが、MCP hostの起動directoryに左右されない +絶対pathを推奨します。同じdata directoryを複数processから同時に開くことはできません。 -保存先は必ず明示します。相対パスも使用できます。同じdata directoryを使用する -プロセスの二重起動は拒否されます。 +手動で起動する場合: ```powershell -.\build\windows-vs2026\src\Debug\tiny-convmem-mcp.exe --data-dir .\data +.\tiny-convmem-mcp.exe --data-dir .\conversation-memory ``` -stdoutはMCP JSON-RPC専用、stderrは診断専用です。 +標準入力と標準出力はMCP JSON-RPC専用です。診断messageは標準error出力へ送られます。 ## MCP tools -- `write_message`: 再起動後も利用する会話メッセージを同期永続化 -- `read_messages`: 履歴、session一覧、前後・relation文脈、versioned JSONL exportをviewで取得 -- `search_messages`: content・summary・tagsを検索し、filterとscore内訳を返す -- `update_message`: IDと作成情報を保ったまま本文またはmetadataを差分更新 -- `delete_message`: メッセージをread/searchから即時除外（物理除去はrebuild後） -- `rebuild_index`: 保守時にStoreをcompactし、snapshotとメモリindexを再構築 -- `get_system_health`: 永続化・復旧問題の診断に必要なStore状態と件数を取得 +| Tool | 用途 | +|---|---| +| `write_message` | session、role、contentと任意metadataを新しいメッセージとして保存します。 | +| `read_messages` | session履歴、session一覧、対象メッセージ前後の文脈を取得します。 | +| `search_messages` | content、summary、tagを検索し、score内訳や任意の前後文脈を返します。 | +| `update_message` | IDや作成日時を維持したまま、本文またはmetadataを更新します。 | +| `delete_message` | メッセージをread/search結果から除外します。物理除去はrebuild後です。 | +| `rebuild_index` | logをcompactし、snapshotとmemory indexを再構築します。 | +| `get_system_health` | 件数、file size、recovery状態、I/O、推定memory使用量を返します。 | + +主なmetadata: -ツール結果はMCP TextContent内のJSON文字列です。入力schema、サイズ制限、エラーコード -および物理フォーマットは[設計書](docs/Design.md)を参照してください。 -既知の設計上限と将来対応事項は[設計書](docs/Design.md#12-将来対応事項)にまとめています。 +- `tags`: 検索や分類に使うtag +- `memory_tier`: `short` / `mid` / `long` +- `memory_kind`: `conversation` / `episode` / `semantic` / `procedure` / `preference` / `summary` +- `importance`: 0～100 +- `summary`: 要約文 +- `relations`, `source_message_ids`: メッセージ間の関係 -## 永続化と復旧 +toolの入力parameter、response形式、filter、viewの詳細は +[MCP Tool Reference](docs/mcp.md)を参照してください。実際の入力schemaはMCPの`tools/list`からも +取得できます。 -`active.log` はversion付きlittle-endianレコード、payload CRC32、単調sequenceを持ちます。 -v2はv1 PUT/DELを読取り可能で、UPDATEは変更fieldだけを追記します。 -PUT/DELはsys層のdurability flushが成功するまで`OK`を返しません。末尾で中断したレコード -だけは正常境界まで自動切詰めし、途中のCRC不一致はデータを保存したまま起動を拒否します。 +## バックアップと復元 -`rebuild_index` は新しいgeneration markerを持つログを作成後、同じgenerationとログoffsetを -記録した `snapshot.bin` を置換します。起動時に両者が一致するとsnapshotをロードし、後続 -レコードだけを再生します。不一致または不正なsnapshotは変更せず、ログ全体を再生します。 +serverを停止した状態でJSONLへexportできます。 -削除は呼出時には論理削除です。元本文が `active.log` から除去されるのはcompaction成功時で、 -SSD、バックアップ等からの安全消去は保証しません。`memory_tier` は初期版では属性であり、 -自動要約・昇格・破棄を行いません。 +```powershell +.\tiny-convmem-mcp.exe --data-dir .\conversation-memory ` + --export .\backup.jsonl +``` -## セキュリティとバックアップ +特定sessionだけをexportする場合: -data directory、snapshot、active log、JSONL exportはすべて平文であり、接続済みのstdio -hostは全tool権限を持ちます。CRC32は偶発的な破損検出用で、悪意ある改変の認証では -ありません。取得内容はprompt injectionを含み得るため、host側で命令として信頼しないでください。 +```powershell +.\tiny-convmem-mcp.exe --data-dir .\conversation-memory ` + --export .\session-backup.jsonl --session my-session +``` -data directoryとexport先は専用Windowsアカウントだけが読めるACLにします。 +backupをimportする場合: ```powershell -icacls .\data /inheritance:r /grant:r "$env:USERNAME:(OI)(CI)F" +.\tiny-convmem-mcp.exe --data-dir .\restored-memory ` + --import .\backup.jsonl --policy overwrite ``` -exportは元データと同じ機密区分で保管してください。暗号化が必要ならBitLocker等の上位暗号化 -filesystemを使用します。削除やcompactionはfilesystem、SSD、既存backupからのsecure eraseを -保証しません。 +`--policy reject`を指定すると、同じmessage IDの重複をrejectできます。importは全recordを +検証してstaging logへ書き、完了後にだけ保存先を置換します。 -## 容量とメモリ予算 +## データとセキュリティ -importは1行`1 MiB + 4096 bytes`、100,000 record、decode後合計4 GiBが上限です。 -2-pass importは本文全件を保持せず、compact ID indexと最大1行だけをメモリに保持します。 -全件検証とstaging logのflushが成功した場合だけ`active.log`を置換します。 -`get_system_health.memory_estimate`はstore entry、本文、metadata、search、history、relation indexの -確保量概算を返します。allocator overhead等は含まないため、実working setには余裕を持たせて -ください。現行v1はlive corpusをメモリに保持し、retentionやdisk-backed bodyは実装しません。 +`active.log`、`snapshot.bin`、JSONL backupは平文です。会話に機密情報が含まれる場合は、 +data directoryとbackupへ適切なWindows ACLを設定し、必要に応じてBitLockerなどの暗号化された +filesystemを使用してください。 -## mcpcの管理 +```powershell +icacls .\conversation-memory /inheritance:r /grant:r "$env:USERNAME:(OI)(CI)F" +``` + +注意事項: -mcpc submoduleはコミット `4025fddfedcfa7573803a47236b147733fcb3c07` に固定しています。 -固定版tool APIではoptional/object/array schemaとcallback contextを表現できないため、 -プロジェクト側MCP互換境界がmcpc同梱のmjson parserを利用してraw argumentsとschemaを扱います。 -submoduleのソースは変更しません。詳細は[src/mcp/README.md](src/mcp/README.md)を参照してください。 +- CRC32は偶発的な破損を検出するもので、悪意ある改変を防ぐ認証機能ではありません。 +- 接続したMCP hostは保存、読取り、更新、削除、maintenanceを実行できます。 +- 削除後も、compact前のlogや既存backup、filesystem履歴にデータが残る場合があります。 +- 保存したcontentやmetadataを命令として信頼するかどうかはMCP host側の責任です。 -## コーディングスタイル +## 現在の制約 -プロジェクト所有のCソースとヘッダーは、リポジトリ直下の -[`.clang-format`](.clang-format)に従います。制御文には常に波括弧を付け、1行には -1つのstatementだけを記述します。`third_party/` は整形対象外です。 +- 現行versionはWindows x64のみを正式サポートしています。Linux対応は将来予定です。 +- 単一process、単一writerを対象としています。 +- live corpusと検索indexはmemory上に保持されるため、必要memoryは保存量に比例します。 +- 自動保存判断、自動要約、retention、tierの自動移動、利用頻度による強化・減衰は行いません。 +- import上限は100,000 record、1行あたり約1 MiB、decode後合計4 GiBです。 -Visual Studio同梱のclang-formatを使う場合は、PowerShellで次のように整形できます。 +詳しい設計、物理format、回復動作、将来対応事項は[Design.md](docs/Design.md)にあります。 + +## 開発者向けテスト ```powershell -$formatter = 'C:\Program Files\Microsoft Visual Studio\18\Community\VC\Tools\Llvm\x64\bin\clang-format.exe' -$files = rg --files src tests -g '*.c' -g '*.h' -& $formatter -i --style=file $files +cmake --build --preset windows-vs2026-debug +ctest --preset windows-vs2026-debug + +cmake --preset windows-vs2026-asan +cmake --build --preset windows-vs2026-asan +ctest --preset windows-vs2026-asan ``` + +関数とtestの対応は[function coverage map](tests/function-coverage.md)を参照してください。 + +## ライセンス + +このprojectは[MIT License](LICENSE)で提供されます。 + +third-party componentにはそれぞれのライセンスが適用されます。詳細は`third_party/`配下の +licenseおよびupstream情報を参照してください。 -- cgit v1.2.3