Claude Codeアシスタントに長期記憶とナレッジグラフを提供するMemoraの仕組み

Claude CodeやCodex CLIのようなエージェントに長期的なタスクを割り当てたことがある人なら、この感覚を理解できるでしょう。昨日、半日かけて明白ではない認可バグを追跡し、アーキテクチャの制約について議論し、リファクタリングプランを概説しました。今日、新しいセッションを開くと、モデルは昨日拒否したその正確なソリューションを提案してきます。

MEMORY.mdのような通常のテキストメモリファイルは、数週間で手に負えなくなります。コンテキストは重複、矛盾した事実、古いプランで詰まってしまう。MemoraプロジェクトはModel Context Protocol（MCP）を通じてこれを解決し、散らかったエージェントのメモを構造化されたナレッジグラフに変換します。

内部構造と、なぜ重要なのか

MemoraはPython MCPサーバーとして動作し、データをローカルSQLiteデータベースまたはクラウドストレージ（Cloudflare D1、S3、R2）に保存します。重要なのは単に文字列を保存するのではなく、システムが新しい事実をどのように処理するかです。

エージェントがタスクを完了してコンテキストを保存したいとき、データ吸収コマンド（absorb）を呼び出します。組み込みの言語モデルが新しい事実を既存のレコードと照合し、重複、更新、矛盾、接続、または本質的に新しい知識として分類します。

情報が古いエントリを更新する場合、Memoraはバージョン連鎖を構築します。古いレコードは痕跡もなく削除されません——古くなったとしてマークされ、変更履歴が保持されます。通常の検索中、エージェントは現在のスナップショットのみを表示しますが、必要に応じて完全な振り返りを取得できます。

実践においてこのプロジェクトを際立たせるもの

このリポジトリは、エージェントの標準的なRAGメモリが深刻な欠如を抱えているいくつかのエンジニアリングソリューションを統合しています。

1. スマートな重複排除とテーマ別サマリー

モデルに類似したテキストチャンクを数十個提供する代わりに、このツールはトピック別に事実を統合します。memory_digest(topic)メソッドは、関連するすべてのメモリ、オープンなTODO、発見されたバグとその接続を1回の呼び出しで収集します。

重複は自動的に追跡されます：

# Поиск похожих записей через векторную близость и LLM-анализ
memory_find_duplicates(min_similarity=0.7, max_similarity=0.95, limit=10, use_llm=True)

# Объединение записей с нужной стратегией
memory_merge(source_id=123, target_id=456, merge_strategy="append")

比較時、LLMは明確な判断を下します：重複、類似した考え、または異なるもの——評価に理由と推奨事項を付記します。

2. 構造化されたドキュメントとアトミックフラグメント

エージェントは短いフレーズではなく、研究レポート全体やアーキテクチャ上の決定（ADR）を記憶する必要がある場合が多いです。マークダウンを単一チャンクとして保存すると、その詳細なセマンティック検索のパフォーマンスが低下します。

Memoraはマークダウンをフラグメントツリーに解析します：

• テーブルは個別の主張になる；
• 番号付きリストはプランアイテムになる；
• 参照リストは参照になる；
• リスクセクションはリスクとして解析される。

各フラグメントは独立してベクトル検索に使用でき、いつでも元のドキュメント全体を检索できます。フラグメントはシステムチェックにより偶発的な削除やマージから保護されています。

3. インタラクティブグラフとWebパネル

MCPサーバーに加えて、ローカルWebインターフェースがポート8765で起動します。ナレッジグラフの表示、タグによる接続のフィルタリング、アクションタイムラインの確認、組み込みのRAGチャットを通じたデータベースとのチャットが可能です。

Webインターフェースチャットは関数呼び出しをサポートしています。ブラウザから直接「メモ#42を削除」や「タスク#10の要件を更新」と依頼すると、データベースに変更を加えます。

設定とEmbeddingの落とし穴

パッケージはpipでインストールします：

pip install memora-mcp

ローカルで外部APIを呼び出さずにEmbeddingを行うには、[local]オプションが便利です：

pip install "memora-mcp[local]"

Claude Codeへの接続は、プロジェクトルートの.mcp.jsonファイルで設定します：

{
  "mcpServers": {
    "memora": {
      "command": "memora-server",
      "args": [],
      "env": {
        "MEMORA_DB_PATH": "~/.local/share/memora/memories.db",
        "MEMORA_ALLOW_ANY_TAG": "1",
        "MEMORA_GRAPH_PORT": "8765",
        "MEMORA_EMBEDDING_STRICT": "1"
      }
    }
  }
}

プロジェクト作者は1つの一般的な設定ミスについて正直に警告しています。MemoraはLLM用（例：OpenRouter）とベクトル表現用（例：Cloudflare Workers AIまたはOpenAI）のプロバイダを分離できます。

推論にOpenRouterを使用する場合は覚えておいてください：OpenRouterにはEmbeddingsエンドポイントがありません。設定で間違えてMEMORA_EMBEDDING_STRICT=1フラグを設定しなかった場合、サーバーは暗黙のうちに原始的なTF-IDFキーワード検索にフォールバックします。データベースは応答を続けますが、ベクトル検索の品質は気づかないうちに低下します。厳格モードでは、ベクトル化エンドポイントを利用できない場合、即座にエラーをスローします。

Neovimユーザーには、Telescope統合という形で嬉しいボーナスがあります：memora.luaプラグインを使用すると、コード編集中にホットキーで直接メモリを検索できます。

このプロジェクトの対象者

Memoraは、Claude Code、Codex CLI、カスタムMCPベースのエージェントを長期的なプロジェクトで активно 使用している人に適しています。これはエージェント開発における主な課題——セッション再起動間のコンテキスト消失——に対処します。

重複で散らかったナレッジベースを防ぎ、タスクとアーキテクチャ上の決定の間の関係を明確に視覚化する必要があるなら、このツールを試す価値は確実にあります。ソースコードはMITライセンスでagentic-box/memoraリポジトリで公開されています。