zaxy

Zaxy is a production-grade memory system designed for AI agent teams, with the core goal of turning an agent's context into an auditable project memory network. It captures parent tasks, work sessions, tool observations, cited findings, conflict reviews, approval packages, and accepted merge write-backs, forming a queryable, replayable, and inspectable persistent history.

Purpose

Zaxy solves the problem of agents "remembering what happened, citing sources, and avoiding turning project state into a pile of Markdown files and vector chunks." It is aimed at agent teams that need receipts, emphasizing auditable memory, agent team coordination, and local-first operation.

Key Capabilities

• Auditable memory: every accepted fact can be traced back to Eventloom history.
• Agent team coordination: parent sessions and work sessions remain isolated until findings are reviewed and merged.
• Local-first runtime: uses an embedded LadybugDB graph projection by default, with no Neo4j sidecar required.
• MCP-native integration: Codex, Claude Code, Cursor, VS Code, Hermes Agent, LangGraph, CrewAI, and AutoGen can use the same memory interface.
• Immutable audit trail: Eventloom append-only JSONL with a SHA-256 hash chain.
• Bi-temporal graph: facts have validity windows (valid_from, valid_to).
• Hybrid extraction: rule-based extraction for typed events (60–80% cost reduction), with LLM as a fallback.
• Hybrid retrieval: exact + keyword + vector + graph traversal, with configurable fusion weights.
• Session sharding: one Eventloom log per agent/session, sharing the same graph.
• Observability: optional Pathlight tracing, breakpoints, and diff support via zaxy-memory[pathlight].
• Hardened local defaults: bounded MCP input, safe session IDs, embedded graph projection without a sidecar, and optional admin tokens for replay/invalidation.

Usage

The PyPI distribution package name is zaxy-memory, while the import package and console command remain zaxy.

Installation and initialization:

• A bare zaxy init sets up the local embedded graph posture, repository-local profile, deterministic capture configuration, genesis event, and heartbeatand MCP guidance.
• For Codex, the printed activation launcher starts the managed capture monitor locally when the configuration exists; pass --capture start only when you want init itself to start the monitor before opening Codex.
• The default human output is compact and action-first; add --verbose when you need full setup diagnostics, optional checks, fallback commands, recovery guidance, and notes.
• For automation scenarios use zaxy init --json, which preserves the original bootstrap fields and adds setup.status, setup.issues, setup.pending, readiness.status, readiness.reasons, readiness.actions, and structured readiness.action_items.
• For Codex, zaxy init --codex-mcp-install auto is the default. It writes or reuses the user-level Codex MCP configuration without replacing an existing zaxy server entry; if there is no safe configuration target, it prints a copyable codex mcp add command; if the existing zaxy entry differs, it requires review before replacement.
• Both Codex paths keep the server workspace-neutral. After init, start or restart Codex via the printed zaxy activate codex ... --launch command so that both the MCP server list and the Zaxy activation package are loaded.

Run the single-agent memory example: local data lives under .eventloom/, with one append-only JSONL file per session.

Other integrations:

• The Claude Code alternative to Codex.
• The Hermes Agent approach.
• Repository development uses pip install -e ".[dev]", ./scripts/setup.sh, and zaxy status. Start the Docker sidecar only for integration tests or explicit backend comparisons. Production setups write Docker secret files to ./secrets/.

Optional components:

• A normal installation uses embedded LadybugDB. Install zaxy-memory[neo4j] only when you need the optional Neo4j sidecar,Install zaxy-memory[pathlight] only when you need Pathlight tracing.
• Zaxy also includes an observe-only OpenAI-compatible packet analyzer for model call provenance. It forwards packets to a configured upstream endpoint and records llm.packet.completed events to Eventloom, but does not act as a router.

When it applies

• Agent teams that need auditable, replayable project memory.
• Agent workflows that need cited sources and avoid fragmenting project state.
• Local-first deployments using MCP-compatible frameworks (Codex, Claude Code, Cursor, VS Code, Hermes Agent, LangGraph, CrewAI, AutoGen).
• Agent memory scenarios that need bitemporal facts, hybrid retrieval, and graph reasoning.

Limitations and caveats

• Benchmark claims have been withdrawn (2026-07-03). The previous LongMemEval numbers were withdrawn: they were produced in oracle mode (on average about 1.9 candidate sessions per question, so Recall@5/citation coverage was about 1.0 by construction rather than through retrieval), and the preference question score depended on a hardcoded answer table that has been removed. Zaxy currently does not publish LongMemEval scores. A real full-haystack LongMemEval run is planned; until then, treat the earlier 0.956 / 0.910 / 1.000 numbers as withdrawn. The Harvey LAB claims are also pending the same audit.
• Production secrets support Docker/Kubernetes-style secret files; direct environment variables take precedence over their *_FILE variants.
• Test-first (Karpathy rule): every public function has a test. Unit tests mock external services, and integration tests use Docker for optional sidecar backends. The coverage threshold is >=92%, enforced by CI. Lint/format uses ruff, and types use mypy.
• Release: the PyPI distribution name is zaxy-memory, because zaxy is already taken on PyPI. Release versions are built from GitHub Actions and uploaded using PyPI Trusted Publishing with GitHub OIDC.The import package and console command are still zaxy. Before publishing, run zaxy doctor --release-smoke to verify the package version, changelog entry, release workflow, tokenless release posture, and lightweight LangGraph example.

Documentation

Public static site: site/index.html; Why Zaxy: docs/why-zaxy.md; Getting started: docs/getting-started.md; MCP quickstart: docs/mcp-quickstart.md; Architecture: docs/architecture.md; Configuration: docs/configuration.md; MCP interface: docs/mcp.md; Memory export contract: docs/export-contract.md; Eventloom contract: docs/eventloom.md; Graph schema: docs/graph-schema.md; Retrieval: docs/retrieval.md; Benchmarks: docs/benchmarks.md; LLM packet analyzer: docs/packet-analyzer.md; Embeddings: docs/embeddings.md; Security: docs/security.md; Operations and deployment: docs/operations.md, docs/deployment.md, docs/runbook.md; Python API: docs/api.md; Stability commitment: docs/stability-commitment.md; Migration guide: docs/migration.md. Archived benchmark iteration notes, release drafts, and research notes are located in docs/archive/, docs/announcements/, and docs/research/. Contributing: CONTRIBUTING.md.