MCP-based Long-Term Memory System for AI Agents
ChronosGraph は、AIエージェント（Claude Code / Gemini CLI / Cursor 等）にセッションを跨いだ永続的な長期記憶を提供する Model Context Protocol (MCP) サーバーです。
- 多層記憶グラフ (MAGMA): 情報を単なるベクトルとして保存するのではなく、時間軸を伴うグラフ構造として保持。Episodic（経験）・Semantic（知識）・Procedural（手順）の変遷を正確に追跡します。
- 動的忘却アルゴリズム: 指数関数的な減衰モデルと重要度評価により、記憶の肥大化を防ぎつつ、重要な教訓を「意味記憶」として抽出します。
- RL 拡張ポイント: 将来の強化学習（PPO 等）統合に向けたインターフェースを設計。ユーザーとの対話を通じたエージェントの行動論理の継続的アップデートを可能にします。
- ハイブリッド検索 — ベクトル検索 + キーワード検索 + グラフトラバーサルを RRF で融合
- 多層記憶モデル — Episodic / Semantic / Procedural の自動分類
- 時間的減衰 — 指数関数的減衰スコアで古い記憶を自動アーカイブ
- 重複排除 — Append-only 置換 + SUPERSEDES グラフエッジで変遷を追跡
- ライトウェイトモード — SQLite + sqlite-vec でゼロ設定で起動
- スケーラブル — PostgreSQL + Neo4j + Redis への切り替え対応
- RL 拡張ポイント — ActionLogger / RewardSignal / PolicyHook インターフェース
Tip
人間は設定を打ち間違えることがあります。 このプロジェクトのインストールと設定は、AIエージェント（Claude Code / Gemini CLI / Cursor 等）に丸投げすることを強く推奨します。
リポジトリをクローンせずに、uvx を使用して MCP サーバーとして即座に実行することも可能です。Claude Desktop 等の設定に以下のようなエントリを追加してください：
{
"mcpServers": {
"chronos-graph": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/yohi/chronos-graph.git",
"context-store"
],
"env": {
"OPENAI_API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}リポジトリをクローンしている場合は scripts/generate_config.py を実行して設定を自動生成できます（例: python scripts/generate_config.py --method uvx --output claude）。クローンしない場合は生成される JSON を MCP クライアント設定に手動で追加してください。
以下のプロンプトをコピーしてエージェントに渡してください：
Install and configure ChronosGraph by following the instructions here:
https://raw.githubusercontent.com/yohi/chronos-graph/refs/heads/master/README.md
For Agents (AIエージェント向け手順)
あなたがターミナル操作可能なAIエージェントであるなら、以下の手順でインストールとセットアップを自律的に遂行してください：
- [ ] 依存関係の解決:
uv(推奨) またはpipを使用して、開発用依存関係をインストールしてください。uv sync --all-extrasまたはpip install -e ".[all]"
- [ ] 環境設定:
.env.exampleを.envにコピーし、必要な環境変数を設定してください。EMBEDDING_PROVIDERはopenaiがデフォルトですが、必要に応じてlocal-modelなどに切り替えてください。
- [ ] 動作確認:
- ユニットテストを実行して、環境が正しく構築されているか確認してください。
uv run pytest tests/unit/ -v
- [ ] MCP設定の生成:
uv run python scripts/generate_config.py > mcp_config.jsonを実行し、MCPクライアント用の設定ファイルを生成してください。
上記の全手順を、ユーザーと対話しながら一括で行うには bash scripts/bootstrap.sh を実行してください。
フラグを使用して非対話的に実行することも可能です：
bash scripts/bootstrap.sh --backend sqlite --embedding openai --graph true --mcp-output cursor各フラグの詳細は AGENTS.md を参照してください。
PostgreSQL + Neo4j + Redis を使用する場合：
docker compose up -d.env でバックエンドを切り替える：
STORAGE_BACKEND=postgres
GRAPH_ENABLED=true
CACHE_BACKEND=redis
POSTGRES_HOST=localhost
POSTGRES_PASSWORD=dev_password
NEO4J_PASSWORD=dev_password
REDIS_URL=redis://localhost:6379| 環境変数 | デフォルト | 説明 |
|---|---|---|
STORAGE_BACKEND |
sqlite |
ストレージバックエンド (sqlite / postgres) |
SQLITE_DB_PATH |
~/.context-store/memories.db |
SQLite DB ファイルパス |
EMBEDDING_PROVIDER |
openai |
埋め込みプロバイダー (openai / local-model / litellm / custom-api) |
OPENAI_API_KEY |
`` | OpenAI API キー |
LOCAL_MODEL_NAME |
cl-nagoya/ruri-v3-310m |
ローカルモデル名（詳細は 埋め込みモデル選定ガイド を参照） |
GRAPH_ENABLED |
false |
グラフ機能の有効化 |
DECAY_HALF_LIFE_DAYS |
30 |
記憶の半減期（日数） |
ARCHIVE_THRESHOLD |
0.05 |
アーカイブ閾値 |
SIMILARITY_THRESHOLD |
0.70 |
類似度検索の閾値 |
DEDUP_THRESHOLD |
0.90 |
重複排除の閾値 |
DEFAULT_TOP_K |
10 |
デフォルト検索件数 |
GRAPH_MAX_LOGICAL_DEPTH |
5 |
グラフ検索の最大論理深さ |
URL_FETCH_CONCURRENCY |
3 |
URL フェッチの同時実行数 |
ALLOW_PRIVATE_URLS |
false |
プライベート URL の許可 (SSRF 対策) |
.env.example に全設定の一覧があります。
| ツール | 説明 |
|---|---|
memory_save |
テキストを記憶として保存 |
memory_save_url |
URL からコンテンツを取得して保存 |
memory_search |
ハイブリッド検索（ベクトル + キーワード + グラフ） |
memory_search_graph |
グラフトラバーサル検索 |
memory_delete |
記憶を削除 |
memory_prune |
古い記憶をクリーンアップ |
memory_stats |
ストレージの統計情報を取得 |
| リソース URI | 説明 |
|---|---|
memory://stats |
ストレージ統計情報 |
memory://projects |
プロジェクト一覧 |
MCP Client (Claude / Cursor / etc.)
│ MCP Protocol (stdio / SSE)
▼
ChronosGraph MCP Server (FastMCP)
│
Orchestrator
├── Ingestion Pipeline
│ Adapter → Chunker → Classifier → Embedding → Deduplicator → GraphLinker
├── Retrieval Pipeline
│ QueryAnalyzer → [VectorSearch + KeywordSearch + GraphTraversal] → ResultFusion → PostProcessor
└── Lifecycle Manager
DecayScorer → Archiver → Consolidator → Purger
Storage Layer (Protocol-based)
├── SQLiteStorageAdapter (sqlite-vec + FTS5)
├── SQLiteGraphAdapter (recursive CTE)
├── PostgresStorageAdapter (pgvector + pg_bigm)
├── Neo4jGraphAdapter
├── InMemoryCacheAdapter
└── RedisCacheAdapter
開発環境のセットアップやワークフローの詳細は AGENTS.md を参照してください。
# テスト実行
uv run pytest tests/unit/ -v
# E2E 統合テスト（外部サービス不要）
uv run pytest tests/integration/test_e2e.py -v
# リント
ruff check src/ tests/
ruff format --check src/ tests/
# 型チェック
mypy src/本プロジェクトでは、コード品質を保つために pre-commit を活用しています。
- コミット時 (
pre-commit):ruff(Lint/Format) が自動実行されます。ホスト側でのコミットも可能です。 - プッシュ時 (
pre-push):mypy(型チェック) が実行されます。依存ライブラリが必要なため、devcontainer内またはuv sync済みの環境での実行を推奨します。
MIT License — LICENSE