Ebb — エージェントファーストのナレッジグラフ

AIエージェントのための長期記憶を、グラフとして構築。関連性は最近性で重み付けされた接続強度です。知識を再利用すると生き続け、未使用の知識は減衰してアーカイブされ、人間が承認するまで何も削除されません。組み込み（インフラ不要）またはNeo4j（本番）で動作します。

このシステムを支える2つのメカニズム（接続重み付け関連性と時間減衰）は、ネイティブなグラフ操作であり、どちらも深い先行研究があります（PageRank/中心性、認知科学からのACT-Rベースレベル活性化と拡散活性化、間隔反復忘却曲線）。これは、その系譜をエージェントメモリに特化して実装した、小さく誠実な実装です。

このように構築された理由

1. エンジンとインターフェースは分離されています。 グラフストアは小さなインターフェース（GraphStore）の背後にあります。エージェントとスコアリングロジックは特定のデータベースに触れることはないため、今日は組み込みエンジンでまったく同じグラフを実行し、後で1つの環境変数でNeo4jに切り替えることができます。

2. 関連性は最近性で重み付けされており、生の接続数ではありません。 「接続が多いほど関連性が高い」という考え方は、古くて頻繁に参照されるデータを永遠に優遇します。これは、このシステムが排除しようとしているまさに陳腐化データ問題です。ここでは、各エッジの関連性への寄与は、接続が最後に強化された時期に基づく時間減衰係数で乗算されます。昨日強化されたエッジはほぼ全額カウントされ、6か月前に最後に触れたエッジはほぼゼロにカウントされます。接続を再利用する（recall/reinforce）と時計がリセットされるため、関連性は実際にアクティブなものを追跡し、古い知識は自然に沈んでいきます。

デモシードグラフ（python -m ebb.demo）からの証明：

node                             raw#   activation
decision:outcome-pricing            3        6.116   <- fresh, few links, ranks #1
decision:seat-pricing              11        3.077   <- MOST links, ranks #3
...
note:analysis-* (x10)               1        0.051   <- decayed -> archived (tier 4)

置き換えられたシート単位の決定は、グラフ内で最も高い生の接続数を持ちながらも、3分の1のリンクしか持たない新しい決定に次いで3位にランクされています。生の数は負け、最近性が勝ちました。

Related MCP server: Memory Engine MCP

含まれるもの

• グラフモデル — すべてのメモ、決定、会議、人物、クライアント、事実はノードであり、すべての参照はタイムスタンプ付き、型付き、重み付きのエッジです。

• スコアリングエンジン（scoring.py）— 最近性重み付け活性化、指数減衰（設定可能な半減期）、拡散活性化の1ホップ（PageRankのポータブルな代替）、およびティア割り当て。純粋関数で、完全にユニットテスト済みです。

• 4つのアーカイブティア — 1 ホット（デフォルトのリコール）・2 ウォーム（より深いリコール）・3 コールド（アーカイブ済み、オンデマンドのみ）・4 フローズン（削除前に人間の承認待ち）。ピン留めされたノードは自動アーカイブされません。

• MCPサーバー（mcp_server.py）— エージェントインターフェース：remember、recall、connect、reinforce、forget、neighbors、pin、maintain、review_queue、stats。

• 2つのバックエンド — KuzuStore（組み込み、デフォルト）とNeo4jStore（本番）、同じインターフェース、同じCypher形状。

クイックスタート（組み込み — インフラ不要）

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

python -m ebb.demo      # narrated end-to-end walkthrough
pytest -q                 # 11 tests, all green

Dockerもサーバーもポートも不要です。Kùzuはインプロセスのグラフデータベースなので、Ebbは単なるフォルダ（./ebb_db）です。

MCPクライアント（例：Claude Desktop）に接続する

1. claude_desktop_config.example.jsonからebbブロックをクライアントのMCP設定にコピーし、絶対パスを修正します。

2. クライアントを再起動します。ebbツールがツールメニューに表示されます。

3. エージェントはセッションをまたいでrememberでき、関連するものをrecallし、使い続けるものをreinforceできます。減衰とアーカイブは自動で処理されます。

本番モード（Neo4j）

docker compose up -d      # Neo4j + Graph Data Science + APOC
EBB_BACKEND=neo4j NEO4J_PASSWORD=brainbrain python -m ebb.demo

同じコード、同じ動作です。Neo4jではさらにGDSライブラリを利用できるため、scoring.pyの拡散活性化パスは、スケールが必要になったときに本格的なPageRank / 中心性 / コミュニティ検出に昇格できます。（Neo4jバックエンドのCypherは、完全にテスト済みのKùzuバックエンドをミラーリングしています。本番で信頼する前に、ライブインスタンスに対してpytestを実行してください。）

モデルの概要

ノードの活性化 = Σ (edge.weight × decay(age_since_last_reinforced)) + read-recency-bonus、さらに隣接ノードからの同じ減衰ホップを1回加えます。減衰は半減期（デフォルト30日、調整可能）です。ティアは、最もアクティブな非ピン留めノードに対して正規化された活性化に基づいてカットされます。recallはこの活性化をクエリのテキストマッチとブレンドし、各結果が浮上した理由を返します。すべては1か所で調整可能です — ebb/scoring.py::Config。

取り込みアダプターの作成

Ebbはソースに依存しません。remember/connectを呼び出すものは何でもフィードできます。ソース（メモフォルダ、Wiki、課題トラッカー）は、ドキュメントをノードに、リンク/メンションをエッジに、編集タイムスタンプを最近性クロックにマッピングすることでグラフになります。アダプターとそのデータはリポジトリの外に置いてください。

レイアウト

src/ebb/
  model.py        # Node, Edge, tiers
  scoring.py      # decay, activation, spreading, tiering  <- the core
  store.py        # GraphStore interface
  kuzu_store.py   # embedded backend (default)
  neo4j_store.py  # production backend
  engine.py       # Brain: remember/recall/connect/reinforce/maintain/...
  mcp_server.py   # agent-facing MCP tools
  seed.py         # fictional demo graph
  demo.py         # narrated walkthrough
tests/            # 11 tests: scoring + end-to-end
docker-compose.yml

ライセンス

MIT — LICENSEを参照してください。