path: root/README.md

# tiny-convmem-mcp

LLMの会話メッセージをローカルの追記ログへ保存する、Windows向けC17製MCP
サーバです。書込みと削除はディスクへの同期完了後に成功を返し、プロセス再起動時は
ログまたはsnapshotから状態を復旧します。

## 必要環境

- Windows x64
- Visual Studio Community 2026（Desktop development with C++）
- CMake 4.3以降
- Git
- vcpkg（PATHから実行可能であること）

## ビルドとテスト

```powershell
git submodule update --init --recursive
.\scripts\bootstrap.ps1 -Configuration Debug
```

手動実行する場合は次のとおりです。

```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
```

AddressSanitizer構成は独立した`build/windows-vs2026-asan`を使用します。

```powershell
cmake --preset windows-vs2026-asan
cmake --build --preset windows-vs2026-asan
ctest --preset windows-vs2026-asan
```

単体テストにはUTF-8/UTF-16、unaligned binary codec、allocation失敗、short I/Oと
操作別I/O失敗が含まれます。自前関数とテストの対応は
[function coverage map](tests/function-coverage.md)を参照してください。

## 起動

保存先は必ず明示します。相対パスも使用できます。同じdata directoryを使用する
プロセスの二重起動は拒否されます。

```powershell
.\build\windows-vs2026\src\Debug\tiny-convmem-mcp.exe --data-dir .\data
```

stdoutはMCP JSON-RPC専用、stderrは診断専用です。

## 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状態と件数を取得

ツール結果はMCP TextContent内のJSON文字列です。入力schema、サイズ制限、エラーコード
および物理フォーマットは[設計書](docs/Design.md)を参照してください。
既知の課題、診断結果、次タスクは[レビューレポート](docs/Review.md)にまとめています。

## 永続化と復旧

`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は変更せず、ログ全体を再生します。

削除は呼出時には論理削除です。元本文が `active.log` から除去されるのはcompaction成功時で、
SSD、バックアップ等からの安全消去は保証しません。`memory_tier` は初期版では属性であり、
自動要約・昇格・破棄を行いません。

## セキュリティとバックアップ

data directory、snapshot、active log、JSONL exportはすべて平文であり、接続済みのstdio
hostは全tool権限を持ちます。CRC32は偶発的な破損検出用で、悪意ある改変の認証では
ありません。取得内容はprompt injectionを含み得るため、host側で命令として信頼しないでください。

data directoryとexport先は専用Windowsアカウントだけが読めるACLにします。

```powershell
icacls .\data /inheritance:r /grant:r "$env:USERNAME:(OI)(CI)F"
```

exportは元データと同じ機密区分で保管してください。暗号化が必要ならBitLocker等の上位暗号化
filesystemを使用します。削除やcompactionはfilesystem、SSD、既存backupからのsecure eraseを
保証しません。

## 容量とメモリ予算

importは1行`1 MiB + 4096 bytes`、100,000 record、decode後合計4 GiBが上限です。
`get_system_health.memory_estimate`はstore entry、本文、metadata、search、history、relation indexの
確保量概算を返します。allocator overhead等は含まないため、実working setには余裕を持たせて
ください。現行v1はlive corpusをメモリに保持し、retentionやdisk-backed bodyは実装しません。

## mcpcの管理

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)を参照してください。

## コーディングスタイル

プロジェクト所有のCソースとヘッダーは、リポジトリ直下の
[`.clang-format`](.clang-format)に従います。制御文には常に波括弧を付け、1行には
1つのstatementだけを記述します。`third_party/` は整形対象外です。

Visual Studio同梱のclang-formatを使う場合は、PowerShellで次のように整形できます。

```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
```