path: root/README.md

# Tiny ConvMem MCP

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++` workload
- CMake 4.3以降
- Git
- vcpkg（`PATH`から実行可能であること）

## ビルド

repositoryをcloneし、submoduleを取得してからbootstrap scriptを実行します。

```powershell
git submodule update --init --recursive
.\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-release
ctest --preset windows-vs2026-release
```

## MCPクライアントへの登録

MCPクライアントのstdio server設定へ、実行ファイルと保存先を登録します。設定形式は
クライアントによって異なりますが、一般的なJSONの例は次のとおりです。

```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から同時に開くことはできません。

手動で起動する場合:

```powershell
.\tiny-convmem-mcp.exe --data-dir .\conversation-memory
```

標準入力と標準出力はMCP JSON-RPC専用です。診断messageは標準error出力へ送られます。

## MCP tools

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

- `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`からも
取得できます。

## バックアップと復元

serverを停止した状態でJSONLへexportできます。

```powershell
.\tiny-convmem-mcp.exe --data-dir .\conversation-memory `
  --export .\backup.jsonl
```

特定sessionだけをexportする場合:

```powershell
.\tiny-convmem-mcp.exe --data-dir .\conversation-memory `
  --export .\session-backup.jsonl --session my-session
```

backupをimportする場合:

```powershell
.\tiny-convmem-mcp.exe --data-dir .\restored-memory `
  --import .\backup.jsonl --policy overwrite
```

`--policy reject`を指定すると、同じmessage IDの重複をrejectできます。importは全recordを
検証してstaging logへ書き、完了後にだけ保存先を置換します。

## データとセキュリティ

`active.log`、`snapshot.bin`、JSONL backupは平文です。会話に機密情報が含まれる場合は、
data directoryとbackupへ適切なWindows ACLを設定し、必要に応じてBitLockerなどの暗号化された
filesystemを使用してください。

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

注意事項:

- CRC32は偶発的な破損を検出するもので、悪意ある改変を防ぐ認証機能ではありません。
- 接続したMCP hostは保存、読取り、更新、削除、maintenanceを実行できます。
- 削除後も、compact前のlogや既存backup、filesystem履歴にデータが残る場合があります。
- 保存したcontentやmetadataを命令として信頼するかどうかはMCP host側の責任です。

## 現在の制約

- 現行versionはWindows x64のみを正式サポートしています。Linux対応は将来予定です。
- 単一process、単一writerを対象としています。
- live corpusと検索indexはmemory上に保持されるため、必要memoryは保存量に比例します。
- 自動保存判断、自動要約、retention、tierの自動移動、利用頻度による強化・減衰は行いません。
- import上限は100,000 record、1行あたり約1 MiB、decode後合計4 GiBです。

詳しい設計、物理format、回復動作、将来対応事項は[Design.md](docs/Design.md)にあります。

## 開発者向けテスト

```powershell
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情報を参照してください。