cozo-memory

CozoDB Memory MCP サーバー

Cozo Memory を選ぶ理由
LLM の短期記憶には限界があります。標準的な RAG はドキュメントを検索しますが、時間をまたいで事実を結び付けることはできません。Cozo Memory は AI エージェントに永続的で構造化されたメモリを提供します。過去の会話を記憶し、関係性を推測し、矛盾を検出し、ナレッジグラフを探索します。すべてお使いのマシン上で動作し、インテリジェントな処理（クリーンアップ、振り返り、要約、エージェントによるルーティング）には、オプションで Ollama を介したローカル LLM 統合を利用できます。

多くのメモリスタックでは、事実用の SQLite、ベクトル検索用の Chroma、グラフ用の NetworkX など、個別のデータベースを組み合わせています。CozoDB は、これらすべてを単一の組み込みエンジンで置き換えます。リレーショナル、グラフ、ベクトル、全文検索を、単一のクエリ言語と1つのファイルで実現し、同期の遅延もありません。

ハイブリッド検索、Graph-RAG、タイムトラベルに対応した、Claude と AI エージェント向けのローカルファーストなメモリです。すべてお使いのマシン上で動作します。オプションの Ollama 統合により、LLM を活用した処理（クリーンアップ、振り返り、要約、エージェントによる検索）が可能になります。

目次

• クイックスタート
• 主な機能
• 位置付けと比較
• インストール
• 統合
• ドキュメント
• トラブルシューティング

クイックスタート

オプション 1：npm からインストール（推奨）

# Install globally
npm install -g cozo-memory

# Or run directly with npx (no installation needed)
npx cozo-memory

オプション 2：ソースからビルド

git clone https://github.com/tobs-code/cozo-memory
cd cozo-memory
npm install && npm run build
npm run start

次に、MCP クライアント（例：Claude Desktop）にサーバーを追加します。詳しくは、以下の統合をご覧ください。

主な機能

🔍 ハイブリッド検索 - Reciprocal Rank Fusion により、セマンティック検索（HNSW）、全文検索（FTS）、グラフのシグナルを組み合わせ、インテリジェントな検索を実現します。

🧠 エージェントによる検索 - 自動ルーティングエンジンがローカル LLM を介してクエリの意図を分析し、最適な検索戦略（ベクトル、グラフ、コミュニティ）を選択します。

⏱️ タイムトラベルクエリ - CozoDB Validity を介してすべての変更をバージョン管理し、完全な監査履歴とともに、履歴上の任意の時点をクエリできます。

🎯 GraphRAG-R1 に着想を得た適応型検索 - GraphRAG-R1（Yu ら、WWW 2026）に概念的な着想を得て、CozoDB 向けに適応されたインテリジェントなシステムです。Progressive Retrieval Attenuation（PRA）と Cost-Aware F1（CAF）スコアリングを備え、使用状況から学習します。

⏳ 時間的な矛盾の解決 - セマンティック分析と監査記録の保持により、矛盾する観察結果を自動的に検出して解決します。

🏠 100% ローカル - ONNX/Transformers を介して埋め込みを生成し、データはお使いのマシン上に保持されます。一部の高度な機能（クリーンアップ、振り返り、要約、エージェントによる検索）では、ローカル LLM 推論用にオプションの Ollama サービスが必要です。ただし、コアとなる検索、CRUD、グラフ操作はLLM なしで動作します。

🧠 マルチホップ推論 - ベクトルピボットを用いたロジック対応のグラフ走査により、深い関係性の推論を実現します。

🗂️ 階層型メモリ - インテリジェントな圧縮と LLM による要約を備えた、マルチレベルのアーキテクチャ（L0-L3）です。

→ すべての機能を見る | バージョン履歴

位置付けと比較

SQLite + Chroma + NetworkX ではなく CozoDB を選ぶ理由

よくある最初の質問は、「既存のツールを組み合わせればよいのでは？」 です。

必要なもの...	一般的な個別スタック	CozoDB Memory
構造化データとリレーション	SQLite / PostgreSQL	✅ リレーショナルエンジンを標準搭載
セマンティック検索／ベクトル検索	Chroma / Qdrant / Pinecone	✅ 1つのエンジンに HNSW + FTS + RRF を統合
グラフのたどり歩きと推論	NetworkX / Neo4j	✅ ネイティブのグラフクエリ + PageRank
タイムトラベル／バージョン管理	カスタム監査テーブル	✅ Validity によるタイムトラベルを標準搭載
統一クエリ言語	複数の API + 接着コード	✅ すべての次元を横断する単一の Datalog クエリ

核心的な洞察： ほとんどのメモリスタックは、ベクトル検索をグラフ DB に追加するか、グラフ検索をベクトル DB に追加しています。CozoDB は異なります。リレーショナル、グラフ、ベクトル、全文検索をネイティブに統合した単一のエンジンです。つまり、次のような利点があります。

• 1つのクエリ言語（Datalog）ですべての次元にアクセスできます。
• 個別のインデックス間で同期の遅延がありません。
• 「ベクトル検索結果」と「グラフの展開」をつなぐETL ブリッジは不要です。
• 運用対象が少なくなります。データベースファイル、プロセス、依存関係チェーンがそれぞれ1つだけです。

他のメモリソリューションとの比較

ほとんどの「メモリ」MCP サーバーは、次の2種類に分類されます。

1. シンプルなナレッジグラフ：トリプルに対する CRUD 操作で、多くの場合、テキスト検索のみ
2. 純粋なベクトルストア：セマンティック検索（RAG）は可能ですが、複雑な関係の理解は限定的

このサーバーは、その中間の「スイートスポット」を埋めます。CozoDB の統合エンジンを活用し、個別のデータベースをつなぎ合わせるのではなく、ベクトル、グラフ、キーワードのシグナルを組み合わせたローカルのデータベースベースのメモリエンジンです。

機能	CozoDB Memory（このプロジェクト）	公式リファレンス（@modelcontextprotocol/server-memory）	mcp-memory-service（コミュニティ）	データベースアダプター（Qdrant/Neo4j）
バックエンド	CozoDB（グラフ + ベクトル + リレーショナル + FTS を1つのエンジンに統合）	JSON ファイル（memory.jsonl）	SQLite / Cloudflare	特化型 DB（ベクトルまたはグラフのみ）
検索ロジック	エージェント型（自動ルーティング）：ハイブリッド + グラフ + 要約	キーワードのみ／完全一致のグラフ検索	ベクトル + キーワード	ほとんどの場合、1つの次元のみ
推論	あり：暗黙的な知識のためのエンジンを標準搭載	なし	なし（「Dreaming」は統合処理）	なし（検索のみ）
コミュニティ	あり：階層型コミュニティ要約	なし	なし	クラスタリングのみ（要約なし）
タイムトラベル	あり：任意の時点でのクエリ（Validity）	なし（現在の状態のみ）	履歴を利用可能。ネイティブ DB 機能はなし	なし
メンテナンス	Janitor：LLM を活用したクリーンアップ	手動	自動統合	ほとんどの場合、手動
デプロイ	ローカル（Node.js + 組み込み DB）	ローカル（Docker/NPX）	ローカルまたはクラウド	多くの場合、外部 DB サーバーが必要

最大の利点は、インテリジェンスと追跡可能性です。エージェント型検索レイヤーと階層型 GraphRAGを組み合わせることで、純粋なベクトルストアよりも高い精度で、特定の事実に関する質問にも、幅広いテーマに関する質問にも回答できます。

インストール

前提条件

• Node.js 20 以降（推奨）
• RAM：最低 1.7 GB（デフォルトの bge-m3 モデルを使用する場合）
  • モデルのダウンロード：約 600 MB
  • 実行時メモリ：約 1.1 GB
  • ⚡ 負荷が大きすぎますか？ EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2 を使用すると、必要な RAM はわずか 約 400 MB です（埋め込みモデルのオプションを参照）。
• CozoDB のネイティブ依存関係は cozo-node 経由でインストールされます。

オプション：LLM を活用したアクション向けの Ollama

一部の高度なアクションでは、インテリジェントな処理のために Ollama を介してローカル LLM を使用します。コアサーバーは Ollama なしでも動作します（CRUD、検索、グラフ操作）が、次のアクションでは Ollama が必要です。

アクション	目的
cleanup	LLM を利用したオブザベーションの統合
reflect	インサイトの生成、矛盾の検出
summarize_communities	LLM が生成するコミュニティの要約
compact	LLM による要約を使ったセッション／エンティティの圧縮
agentic_search	自動ルーティングのためのクエリ意図の分類

セットアップ（これらの機能が必要な場合）：

# 1. Install Ollama from https://ollama.ai
# 2. Pull a model (e.g. small + fast for dev):
ollama pull demyagent-4b-i1:Q6_K
# 3. Ollama runs automatically on http://localhost:11434

Ollama が起動していない場合、該当するアクションは可能な範囲で LLM を使わない動作に適切にフォールバックするか、明確なエラーメッセージを返します。

npm 経由（最も簡単）

# Install globally
npm install -g cozo-memory

# Or use npx without installation
npx cozo-memory

ソースからのインストール

git clone https://github.com/tobs-code/cozo-memory
cd cozo-memory
npm install
npm run build

Windows クイックスタート

npm install
npm run build
npm run start

注意：

• 初回起動時に、@xenova/transformers が埋め込みモデルをダウンロードします（時間がかかる場合があります）
• 埋め込み処理は CPU 上で行われます

埋め込みモデルのオプション

CozoDB Memory は、EMBEDDING_MODEL 環境変数を使って複数の埋め込みモデルをサポートしています。

モデル	サイズ	RAM	次元数	最適な用途
Xenova/bge-m3（デフォルト）	約 600 MB	約 1.7 GB	1024	高精度、本番環境での使用
Xenova/all-MiniLM-L6-v2	約 80 MB	約 400 MB	384	低スペックのマシン、開発
Xenova/bge-small-en-v1.5	約 130 MB	約 600 MB	384	バランスの取れたパフォーマンス

設定オプション：

オプション 1：.env ファイルを使用（初心者に最も簡単）

# Copy the example file
cp .env.example .env

# Edit .env and set your preferred model
EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2

オプション 2：MCP サーバーの設定（Claude Desktop／Kiro 向け）

{
  "mcpServers": {
    "cozo-memory": {
      "command": "npx",
      "args": ["cozo-memory"],
      "env": {
        "EMBEDDING_MODEL": "Xenova/all-MiniLM-L6-v2"
      }
    }
  }
}

オプション 3：コマンドライン

# Use lightweight model for development
EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2 npm run start

モデルを事前にダウンロード（推奨）：

# Set model in .env or via command line, then:
EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2 npm run download-model

注： モデルを変更すると、既存データの再埋め込みが必要です。モデルは初回使用時に一度だけダウンロードされます。

統合

Claude Desktop

npx を使用（推奨）

{
  "mcpServers": {
    "cozo-memory": {
      "command": "npx",
      "args": ["cozo-memory"]
    }
  }
}

グローバルインストールを使用

{
  "mcpServers": {
    "cozo-memory": {
      "command": "cozo-memory"
    }
  }
}

ローカルビルドを使用

{
  "mcpServers": {
    "cozo-memory": {
      "command": "node",
      "args": ["C:/Path/to/cozo-memory/dist/index.js"]
    }
  }
}

フレームワークアダプター

人気の AI フレームワークとシームレスに統合するための公式アダプター：

🦜 LangChain アダプター

npm install @cozo-memory/langchain @cozo-memory/adapters-core

import { CozoMemoryChatHistory, CozoMemoryRetriever } from '@cozo-memory/langchain';

const chatHistory = new CozoMemoryChatHistory({ sessionName: 'user-123' });
const retriever = new CozoMemoryRetriever({ useGraphRAG: true, graphRAGDepth: 2 });

🦙 LlamaIndex アダプター

npm install @cozo-memory/llamaindex @cozo-memory/adapters-core

import { CozoVectorStore } from '@cozo-memory/llamaindex';

const vectorStore = new CozoVectorStore({ useGraphRAG: true });

ドキュメント： 詳しい例と API リファレンスについては、adapters/README.md を参照してください。

CLI と TUI

CLI ツール

すべての操作に対応するフル機能の CLI：

# System operations
cozo-memory system health
cozo-memory system metrics

# Entity operations
cozo-memory entity create -n "MyEntity" -t "person"
cozo-memory entity get -i <entity-id>

# Search
cozo-memory search query -q "search term" -l 10
cozo-memory search agentic -q "agentic query"

# Graph operations
cozo-memory graph pagerank
cozo-memory graph communities

# Export/Import
cozo-memory export json -o backup.json
cozo-memory import file -i data.json -f cozo

# All commands support -f json or -f pretty for output formatting

コマンドの完全なリファレンスについては、CLI のヘルプを参照してください：cozo-memory --help

TUI（ターミナルユーザーインターフェース）

Python Textual を利用した、マウス操作に対応するインタラクティブな TUI：

# Install Python dependencies (one-time)
pip install textual

# Launch TUI
npm run tui
# or directly:
cozo-memory-tui

TUI の機能：

• 🖱️ マウス操作に完全対応（ボタンのクリック、スクロール、入力欄の選択）
• ⌨️ キーボードショートカット（q=終了、h=ヘルプ、r=更新）
• 📊 すべての操作に対応するインタラクティブなメニュー
• 🎨 色やアニメーションを備えたリッチなターミナル UI

アーキテクチャの概要

graph TB
    Client[MCP Client<br/>Claude Desktop, etc.]
    Server[MCP Server<br/>FastMCP + Zod Schemas]
    Services[Memory Services]
    Embeddings[Embeddings<br/>ONNX Runtime]
    Search[Hybrid Search<br/>RRF Fusion]
    Cache[Semantic Cache<br/>L1 + L2]
    Inference[Inference Engine<br/>Multi-Strategy]
    DB[(CozoDB SQLite<br/>Relations + Validity<br/>HNSW Indices<br/>Datalog/Graph)]
    
    Client -->|stdio| Server
    Server --> Services
    Services --> Embeddings
    Services --> Search
    Services --> Cache
    Services --> Inference
    Services --> DB
    
    style Client fill:#e1f5ff,color:#000
    style Server fill:#fff4e1,color:#000
    style Services fill:#f0e1ff,color:#000
    style DB fill:#e1ffe1,color:#000

詳しいアーキテクチャのドキュメントについては、docs/ARCHITECTURE.md を参照してください

MCP ツールの概要

インターフェースは統合された 5 つのツールに集約されています。

ツール	目的	主なアクション
mutate_memory	書き込み操作	create_entity、update_entity、delete_entity、add_observation、create_relation、transactions、sessions、tasks、update_observation、batch_delete、manage_tags、batch
query_memory	読み取り操作	search、advancedSearch、context、graph_rag、graph_walking、agentic_search、adaptive_retrieval、list_entities、get_entity_detail、get_session_context、list_sessions
analyze_graph	グラフ分析	explore、communities、pagerank、betweenness、hits、shortest_path、semantic_walk
manage_system	メンテナンス	health、metrics、stats、export、import、cleanup、defrag、reflect、snapshots
edit_user_profile	ユーザー設定	設定や作業スタイルを含むグローバルユーザープロファイルの編集

すべてのパラメーターと例を含む完全な API リファレンスについては、docs/API.md を参照してください

トラブルシューティング

よくある問題

初回起動に時間がかかる

• 初回起動時は、埋め込みモデルのダウンロードに30～90秒かかります（Transformersが約500MBのアーティファクトを読み込みます）。
• これは正常な動作で、発生するのは一度だけです。
• 2回目以降の起動は高速です（2秒未満）。

LLM を活用したアクションには Ollama が必要です

• 次のアクションでは、インテリジェントな処理のためにローカル LLM を使用します：cleanup、reflect、summarize_communities、compact、agentic_search
• https://ollama.ai から Ollama をインストールします。
• 使用するモデルを取得します：ollama pull demyagent-4b-i1:Q6_K（または任意のモデル）。
• Ollama がない場合、これらのアクションは LLM を使わない動作にフォールバックするか、明確なエラーを返します。
• コア機能（CRUD、検索、グラフ、推論）は LLM がなくても動作します。

Windows 固有の事項

• 互換性を最大限に高めるため、埋め込み処理には CPU を使用します。
• RocksDB バックエンドを選択する場合は、Visual C++ Redistributable が必要です。

パフォーマンスの問題

• 再起動後の最初のクエリは遅くなります（キャッシュが冷えているため）。
• キャッシュヒット率を確認するには、health アクションを使用します。
• 100k を超えるエンティティを含むデータセットでは、RocksDB バックエンドの使用を検討してください。

パフォーマンス最適化のヒントについては、docs/BENCHMARKS.md をご覧ください。

ドキュメント

• docs/API.md - すべてのパラメーターと例を含む、MCP ツールの完全なリファレンス
• docs/ARCHITECTURE.md - システムアーキテクチャ、データモデル、技術的な詳細
• docs/BENCHMARKS.md - パフォーマンス指標、評価結果、最適化のヒント
• docs/FEATURES.md - 使用例を含む、機能の詳細なドキュメント
• docs/USER-PROFILING.md - ユーザーの好みのプロファイリングとパーソナライズ
• CHANGELOG.md - バージョン履歴とリリースノート
• CONTRIBUTING.md - 開発ガイドライン

開発

構成

• src/index.ts：MCP サーバーとツールの登録
• src/memory-service.ts：コアビジネスロジック
• src/db-service.ts：データベース操作
• src/embedding-service.ts：埋め込みパイプラインとキャッシュ
• src/hybrid-search.ts：検索戦略と RRF
• src/inference-engine.ts：推論戦略
• src/api_bridge.ts：Express API ブリッジ（オプション）

スクリプト

npm run build        # TypeScript Build
npm run dev          # ts-node Start of MCP Server
npm run start        # Starts dist/index.js (stdio)
npm run bridge       # Build + Start of API Bridge
npm run benchmark    # Runs performance tests
npm run eval         # Runs evaluation suite

コントリビューション

コントリビューションを歓迎します！ガイドラインについては、CONTRIBUTING.md をご覧ください。

ライセンス

Apache 2.0 - 詳細については LICENSE をご覧ください。

謝辞

以下を使用して構築されています：

• CozoDB - 組み込みグラフデータベース
• ONNX Runtime - ローカルでの埋め込み生成
• Transformers.js - Xenova/bge-m3 モデル
• FastMCP - MCP サーバーフレームワーク

研究上の基盤：

• GraphRAG-R1 (Yu et al., WWW 2026) - 適応型検索の概念的な着想元
• HopRAG (ACL 2025) - マルチホップ推論の概念的な着想元
• T-GRAG (Li et al., 2025) - 時間的な競合解決の概念的な着想元
• FEEG Framework (Samuel et al., 2026) - クエリ意図分類の概念的な着想元
• Allan-Poe (arXiv:2511.00855) - 動的フュージョンの概念的な着想元