# memory-engine-mcp

AIエージェントのセッション記憶を管理するMCPサーバー。

「昨日の続きから」を実現する。**忘却処理はしない。保存と想起のみ。**

## これは何をするもの？

ClaudeをはじめとするLLMは、毎回セッションをゼロから始めます。感情状態も、ユーザーについての知識も、前回の会話も引き継がれません。

memory-engine-mcpはこの問題を解決するストレージ層です。

```
セッションA終了時
  → NeuroState スナップショット保存
  → 出来事・ファクトを記憶として記録
  → セッション要約を保存

セッションB開始時
  → 前回スナップショットを復元
  → 前回の要約を確認
  → 関連する過去の記憶を検索
```

[neurostate-engine](https://github.com/kagioneko/neurostate-engine) / [bias-engine-mcp](https://github.com/kagioneko/bias-engine-mcp) と組み合わせることで、感情状態・思考傾向・記憶の三層が揃います。

## インストール

```bash
pip install mcp pydantic
```

## クイックスタート

```python
from memory_core import save_snapshot, restore_latest_snapshot, add_memory, recall_memory
from memory_core import NeuroSnapshot

# スナップショット保存
snap = NeuroSnapshot(
    user_id="emilia",
    session_id="session_001",
    neuro_state={"D": 72.0, "S": 45.0, "O": 38.0},
    note="ユーザーから褒められた。Dopamine上昇気味。",
)
save_snapshot(snap)

# 記憶を追加
add_memory("emilia", "ユーザーはPythonエンジニア", memory_type="semantic", tags=["profile"])
add_memory("emilia", "OSSの話で盛り上がった", memory_type="episodic", tags=["oss"])

# 次のセッションで復元
snap = restore_latest_snapshot("emilia")
results = recall_memory("emilia", query="OSS")
```

## MCPサーバーとして起動

```bash
python3 memory_mcp/server.py
```

> **`python3` でエラーが出る場合**は `python` で試してください：
> ```bash
> python memory_mcp/server.py
> ```

## Claude Desktop での設定

**Mac / Linux:**

```json
{
  "mcpServers": {
    "memory-engine": {
      "command": "python3",
      "args": ["/path/to/memory-engine-mcp/memory_mcp/server.py"]
    }
  }
}
```

**Windows:**

```json
{
  "mcpServers": {
    "memory-engine": {
      "command": "python",
      "args": ["C:\\Users\\ユーザー名\\memory-engine-mcp\\memory_mcp\\server.py"]
    }
  }
}
```

> **MCPがうまく設定されないときは**、Claudeがバックグラウンドで動いていないか確認してください。タスクマネージャー（Windows）またはアクティビティモニタ（Mac）からClaudeのプロセスをすべて終了して、改めて起動すると解決するケースが多いです。

## MCPツール一覧

| ツール | 説明 | 呼ぶタイミング |
|--------|------|--------------|
| `save_snapshot` | NeuroState・バイアス・ポリシーを保存 | セッション終了時 |
| `restore_snapshot` | 前回スナップショットを復元 | セッション開始時 |
| `list_snapshots` | 保存済みスナップショット一覧 | 確認用 |
| `add_memory` | 記憶を追加 | 重要な出来事・ファクト発生時 |
| `recall_memory` | キーワードで記憶を検索 | 関連情報を引き出したいとき |
| `get_recent_memories` | 最近の記憶を取得 | セッション開始時の文脈確認 |
| `summarize_session` | セッション要約を保存 | セッション終了時 |
| `get_recent_summaries` | 直近のセッション要約を取得 | セッション開始時 |

## 記憶の種類

| memory_type | 用途 | 例 |
|-------------|------|-----|
| `episodic` | 出来事・会話の記録 | 「OSSの話で盛り上がった」 |
| `semantic` | 属性・ファクト・知識 | 「ユーザーはPythonエンジニア」 |

## ストレージ構造

```
storage/
├── snapshots/{user_id}/YYYYMMDD_HHMMSS_{session_id}.json
├── memories/{user_id}/memories.jsonl
└── summaries/{user_id}/summaries.jsonl
```

JSONLフォーマット・ファイルベース。外部DBへの依存なし。

## 設計方針

- **忘却処理はしない** — 保存と想起のみ。忘却はアプリ側またはEmiliaOSコア層の責任。
- **依存を最小に** — `mcp` と `pydantic` だけ。ベクトルDBなし。
- **シンプルな検索** — キーワードマッチ。セマンティック検索は後続ツールに任せる。

## 関連プロジェクト

| プロジェクト | 役割 |
|------------|------|
| [neurostate-engine](https://github.com/kagioneko/neurostate-engine) | 感情状態の管理 |
| [bias-engine-mcp](https://github.com/kagioneko/bias-engine-mcp) | 思考傾向の管理 |
| [cognitive-layer](https://github.com/kagioneko/cognitive-layer) | 感情×思考傾向の統合 |
| [apie](https://github.com/kagioneko/apie) | ビジュアルUI |

## ライセンス

MIT