Zaxy — event-sourced agent memory with cited checkout and reversible forgetting (stdio/SSE via PyPI)

Zaxy

根拠を示す必要があるエージェントチーム向けの本番環境用メモリー。

Zaxy は、エージェントのコンテキストを監査可能なプロジェクトメモリーの基盤へと変換します。親ミッション、ワーカーセッション、ツールによる観察、引用付きの調査結果、矛盾のレビュー、承認パケット、承認済みのマージバックを、クエリ、再生、検査が可能な単一の永続的な履歴として記録します。

内部では、Zaxy は真実の情報源として Eventloom の追記専用 JSONL を使用し、ローカルでの推論には組み込みの LadybugDB グラフ投影を使用します。何が起きたかを記憶し、その出所を引用し、プロジェクトの状態が Markdown ファイルやベクターチャンクの山になるのを避ける必要があるエージェント向けに構築されています。

組み込みの LadybugDB グラフ投影が、デフォルトのローカルランタイムです。

通常のインストールでは組み込みの LadybugDB が使用されます。オプションの Neo4j サイドカーには zaxy-memory[neo4j] を、Pathlight のトレースには zaxy-memory[pathlight] をインストールしてください。

重要な理由

• 監査可能なメモリー：承認されたすべての事実を Eventloom の履歴までたどれます。
• エージェントチームの連携：調査結果がレビューされ、マージされるまで、親セッションとワーカーセッションは分離された状態を保ちます。
• ローカルファーストのランタイム：デフォルトの構成では組み込みの LadybugDB を使用し、Neo4j サイドカーは不要です。
• MCP ネイティブの統合：Codex、Claude Code、Cursor、VS Code、Hermes Agent、LangGraph、CrewAI、AutoGen は、同じメモリーインターフェースを使用できます。

ベンチマークの主張を撤回（2026-07-03）。 以前の LongMemEval の数値は撤回されました。これらは oracle モードで生成されていました（質問あたりの候補セッション数は平均約 1.9 であり、Recall@5／引用カバレッジが約 1.0 だったのは、検索の成果ではなく、構成上そうなっていたためです）。また、嗜好に関する質問のスコアは、その後削除されたハードコードの回答テーブルに基づいていました。Zaxy は現在、LongMemEval のスコアを公開していません。実際の全ハイスタックを対象とした LongMemEval の実行を計画しています。それが実施されるまでは、以前の 0.956／0.910／1.000 という数値は撤回済みとして扱ってください。Harvey LAB の主張についても、同じ監査の結果待ちです。

クイックスタート

インストール、初期化、確認

pipx install zaxy-memory
zaxy init
zaxy memory log --eventloom-path .eventloom --limit 5
zaxy memory bootstrap --eventloom-path .eventloom
zaxy doctor --eventloom-path .eventloom

PyPI のディストリビューション名は zaxy-memory ですが、インポートパッケージ名とコンソールコマンドは引き続き zaxy です。引数なしの zaxy init を実行すると、ローカル組み込みグラフの構成、リポジトリローカルのプロファイル、決定論的なキャプチャ設定、ジェネシスイベント、ハートビート、MCP のガイダンスが設定されます。Codex では、ローカルのキャプチャ設定が存在する場合、出力された有効化ランチャーによって管理対象のキャプチャウォッチャーが起動します。Codex を開く前に init 自体でウォッチャーを起動したい場合に限り、--capture start を渡してください。デフォルトのユーザー向け出力は簡潔で、必要な操作を優先して示します。セットアップの詳細診断、オプションのチェック、フォールバックコマンド、再開方法のガイダンス、注記が必要な場合は、--verbose を追加してください。 自動化では、zaxy init --json によってオンボーディングの生のフィールドが保持され、さらにコマンドとコマンド以外のレビュータスクの両方について、setup.status、setup.issues、setup.pending、readiness.status、readiness.reasons、readiness.actions、構造化された readiness.action_items が追加されます。各構造化アクションには、label、command、元の source、および有効化時の <task> の置き換えやパスが変わっても使えるコマンドの案内など、簡潔な出力向けのヒントを記載した hints が含まれます。インストーラーは、文章を解析せずにこれらのヒントを表示できます。また、setup.summary、readiness.summary、readiness.required_action_count、readiness.reason_count も含まれるため、クライアントの UI はユーザー向け出力を解析せずに簡潔なステータスを表示できます。さらに、readiness.blocking_diagnostics と readiness.non_blocking_diagnostics を分けているため、スクリプトはライブメモリに依存する前に、セットアップの完了、必須アクション、参考情報となる doctor の警告を区別できます。

Codex では、zaxy init --codex-mcp-install auto がデフォルトです。既存の zaxy サーバーエントリを置き換えずに設定できる場合、ユーザーレベルの Codex MCP 設定を書き込むか、既存の設定を再利用します。安全に使用できる設定先がない場合は、コピーして使える codex mcp add コマンドが表示されます。既存の zaxy エントリが異なる場合は、同じ名前のサーバーが Codex によって通知なしに置き換えられる可能性があるため、その設定を確認してから置き換えるよう求められます。確認後、この判断のどちらかを明示的に強制する必要がある場合は、モードを指定してください。

zaxy init --codex-mcp-install user
# or: zaxy init --codex-mcp-install command

どちらの Codex の方法でも、サーバーは特定のワークスペースに依存しません。初期化後、出力された zaxy activate codex ... --launch コマンドを使って Codex を起動または再起動すると、MCP サーバーの一覧と Zaxy の有効化パケットが同時に読み込まれます。出力されるコマンドには --eventloom-path と --workspace-root の値が明示されているため、別のシェルからコピーした場合でも、初期化したリポジトリが対象になります。

単一エージェントのメモリの例を実行します。

python examples/single_agent_memory.py

ローカルデータは .eventloom/ の下に、セッションごとに 1 つの追記専用 JSONL ファイルとして保存されます。

Codex の代わりに Claude Code を使う場合：

zaxy init . --domain my-project --preset local-claude --infra check

Hermes Agent を使う場合：

zaxy ide-config hermes --install

リポジトリの開発では、pip install -e ".[dev]"、./scripts/setup.sh、zaxy status を使用してください。Docker のサイドカーは、統合テストまたは明示的なバックエンド比較を行う場合に限り起動してください。本番環境のセットアップでは、Docker のシークレットファイルが ./secrets/ の下に作成されます。docs/deployment.md を参照してください。

アーキテクチャ

Agent (LangGraph / Any MCP Client)
    |
    v
MCP Server — memory_append / memory_query / memory_feedback / memory_replay / memory_invalidate
    |
    v
Eventloom (immutable JSONL log)  →  Hybrid Extraction  →  Embedded LadybugDB graph
    |                                                               |
    +—————— Optional Pathlight traces ———————————————→  Query Router
                                                              |
                                                    Hybrid Retrieval
                                                    (exact + BM25 + vector + traversal)

Zaxy には、モデル呼び出しの来歴を分析する、監視専用の OpenAI 互換パケットアナライザーも含まれています。設定された 1 つの上流エンドポイントにパケットを転送し、ルーターとして動作することなく、llm.packet.completed イベントを Eventloom に記録します。LLM Packet Analyzer を参照してください。

公開サイトとドキュメント

• 公開静的サイト：site/index.html
• Zaxy を選ぶ理由：docs/why-zaxy.md
• はじめに：docs/getting-started.md
• MCP クイックスタート：docs/mcp-quickstart.md
• アーキテクチャ：docs/architecture.md
• 設定：docs/configuration.md
• MCP インターフェース：docs/mcp.md
• メモリーエクスポートの契約：docs/export-contract.md
• Eventloom の契約：docs/eventloom.md
• グラフスキーマ：docs/graph-schema.md
• 検索：docs/retrieval.md
• ベンチマーク：docs/benchmarks.md
• LLM パケットアナライザー：docs/packet-analyzer.md
• 埋め込み：docs/embeddings.md
• セキュリティ：docs/security.md
• 運用とデプロイ：docs/operations.md、docs/deployment.md、docs/runbook.md
• Python API：docs/api.md
• 安定性への取り組み：docs/stability-commitment.md
• 移行ガイド：docs/migration.md
• アーカイブされたベンチマークの反復記録、リリース草案、調査メモは docs/archive/、docs/announcements/、docs/research/ にあります。
• コントリビューション：CONTRIBUTING.md

主な機能

• 不変の監査証跡：SHA-256 ハッシュチェーンを備えた Eventloom の追記専用 JSONL。
• 双時点グラフ：事実には有効期間（valid_from、valid_to）があります。
• ハイブリッド抽出：型付きイベントにはルールベース（コストを60～80％削減）を使用し、フォールバックとして LLM を使用します。
• ハイブリッド検索：設定可能な統合重みを使用して、完全一致＋キーワード＋ベクトル＋グラフ走査を組み合わせます。
• セッションのシャーディング：エージェント／セッションごとに1つの Eventloom ログを使用し、グラフは共有します。
• MCP ネイティブ：stdio または SSE 経由で、MCP 互換のあらゆるエージェントフレームワークにそのまま組み込めるメモリーです。
• 可観測性：zaxy-memory[pathlight] により、Pathlight のトレース、ブレークポイント、差分機能をオプションで利用できます。
• セキュリティを強化したローカルのデフォルト設定：MCP 入力の制限、安全なセッション ID、サイドカー不要の埋め込みグラフプロジェクションを備え、リプレイ／無効化用の管理者トークンにもオプションで対応します。

プロジェクト構成

ファイル	役割
src/zaxy/event.py	Eventloom の JSONL I/O とハッシュチェーンの整合性
src/zaxy/extract.py	ハイブリッド抽出エンジンとルールレジストリ
src/zaxy/embedded_graph_store.py	埋め込み型 LadybugDB プロジェクションストア
src/zaxy/graph.py	zaxy-memory[neo4j] 経由で利用する、オプションの Neo4j 双時点ラッパー
src/zaxy/query.py	ハイブリッド検索ルーター
src/zaxy/mcp_server.py	MCP stdio／SSE サーバー
src/zaxy/trace.py	オプションの Pathlight 可観測性フック
src/zaxy/core.py	MemoryFabric オーケストレーター
src/zaxy/session.py	セッションごとの Eventloom ログマネージャー
src/zaxy/security.py	共通の検証と入力制限
src/zaxy/__main__.py	CLI（zaxy serve、zaxy replay など）

本番環境のシークレット

Zaxy は、機密性の高い設定に Docker／Kubernetes 形式のシークレットファイルを使用できます。

変数	シークレットファイル形式
NEO4J_PASSWORD	NEO4J_PASSWORD_FILE
MCP_ADMIN_TOKEN	MCP_ADMIN_TOKEN_FILE
PATHLIGHT_ACCESS_TOKEN	PATHLIGHT_ACCESS_TOKEN_FILE

環境変数を直接指定した場合、対応する *_FILE 形式より優先されます。 本番環境の Compose 設定のベースラインには docker-compose.prod.yml を使用してください。

開発

• テストを先に書く（Karpathy ルール）。すべての公開関数にテストを用意します。
• ユニットテストでは外部サービスをモックします。統合テストでは、オプションのサイドカーバックエンドに Docker を使用します。
• カバレッジの基準：≥92%。CI で適用されます。
• Lint／フォーマット：ruff。型チェック：mypy。

# Run full suite with coverage gate
pytest

# Run integration tests (requires Docker)
./scripts/generate-certs.sh .certs
docker compose --profile integration up -d neo4j-test neo4j-tls
pytest -m integration --no-cov

# Lint and type-check
ruff check src tests
mypy src

# LongMemEval benchmark numbers are WITHDRAWN (see the note at the top of this
# README). The `--dataset .cache/.../longmemeval_oracle.json` path only exercises
# the answer step over pre-selected gold sessions (oracle mode) and does NOT
# measure retrieval on the full LongMemEval haystack; do not publish figures from
# it as a LongMemEval score. A real full-haystack harness is TBD.

# Harvey LAB external memory-ablation comparison
# Consumes externally generated Harvey normalized-result artifacts for Zaxy;
# does not reuse LongMemEval statistics as legal-agent benchmark evidence.
# Current full external Harvey LAB evidence:
# reports/benchmarks/harvey-lab-memory-ablation/publishable-statistics.md
# reports/benchmarks/harvey-lab-memory-ablation/harvey-lab-benchmark.json
# 10/10 tasks, mean criterion pass rate 0.788, +0.184 vs regular/no-memory,
# +0.081 vs article-best task rows, 9/10 wins vs article-best rows.

# Production deployment preflight
scripts/validate-deployment.sh --root .

# Build and validate Python release artifacts
scripts/build-dist.sh --root .

# Verify local release metadata, PyPI Trusted Publishing, and LangGraph smoke
zaxy doctor --release-smoke

# Validate public site and documentation links
scripts/validate-docs.sh --root .

# Clean-repo beta UAT: install into a throwaway workspace and verify init,
# bootstrap, deterministic capture, doctor, and memory checkout.
scripts/beta-uat.sh

# Summarize beta readiness gates without external services.
zaxy doctor --beta-readiness

# Go-live release gate
scripts/release-check.sh --root .

スプリントを完了する前に、テストスイート全体のカバレッジを92％以上に維持する必要があります。

リリースの公開

PyPI では zaxy がすでに使用されているため、配布パッケージ名は zaxy-memory です。公開リリースは GitHub Actions でビルドされ、GitHub OIDC を使用した PyPI Trusted Publishing により https://pypi.org/project/zaxy-memory/ にアップロードされます。インポートパッケージ名とコンソールコマンド名は引き続き zaxy です。

公開前に zaxy doctor --release-smoke を実行して、パッケージのバージョン、変更履歴の項目、リリースワークフロー、トークン不要の公開方式、および依存関係を最小限に抑えた LangGraph の例を検証してください。

ライセンス

MIT