Zaxy
Zaxy is a production memory fabric for agent teams, providing auditable, citeable, and queryable persistent memory through an MCP-native interface. It supports local-first operation with an embedded graph (LadybugDB), optional Neo4j integration, and MCP-native compatibility with frameworks like Codex, Claude Code, Cursor, LangGraph, CrewAI, and AutoGen.
Available tools:
memory_checkout— Primary entry point: retrieve current, cited, prompt-ready memory state for a session. Supports token budgets, replay from a sequence number, and purpose-conditioned guidance.memory_append— Append typed events (e.g.goal.created) to the agent's persistent, immutable memory log for future retrieval.memory_query— Query the temporal knowledge graph with natural language, supporting temporal filters, pagination/cursors, and cross-session scoping.context_assemble— Assemble a replay of recent events plus ranked retrieval results into a single prompt-ready context bundle with optional token budget packing.memory_feedback— Record whether a retrieved memory item was useful, stale, corrected, or reinforced, closing the feedback loop to improve future retrieval.memory_invalidate— Mark a specific fact as invalid at a given point in time (bi-temporal update), preserving full history while surfacing corrections in future checkouts.memory_capabilities— Discover active capabilities, tool profiles, and available tools — useful at session start or when tool awareness is unclear.memory_feeling_of_knowing— Experimental ultra-fast metamemory pre-check (~1ms) that predicts whethermemory_checkoutwould return relevant results, using only in-memory state without embedding or graph calls.
Enables CrewAI agents to use the same memory interface for capturing tool observations, citations, and approved merges into a durable, queryable history.
Integrates with LangGraph agents to provide an immutable event log and graph-based memory for session isolation, conflict review, and hybrid retrieval.
Offers an observe-only packet analyzer that forwards OpenAI-compatible model calls to a configured endpoint and records provenance events in Eventloom.
Zaxy
Production memory for agent teams that need receipts.
Zaxy turns agent context into an auditable project memory fabric. It captures parent missions, worker sessions, tool observations, cited findings, conflict review, approval packets, and accepted merge-back into one durable history that can be queried, replayed, and inspected.
Under the hood, Zaxy uses Eventloom append-only JSONL as the source of truth and an embedded LadybugDB graph projection for local reasoning. It is built for agents that need to remember what happened, cite where it came from, and avoid turning project state into a pile of markdown files and vector chunks.
The embedded LadybugDB graph projection is the default local runtime.
The plain install uses embedded LadybugDB. Install zaxy-memory[neo4j] only for the
optional Neo4j sidecar, and zaxy-memory[pathlight] only for Pathlight tracing.
Why It Matters
Auditable memory: every accepted fact can point back to Eventloom history.
Agent-team coordination: parent and worker sessions stay isolated until findings are reviewed and merged.
Local-first runtime: the default path uses embedded LadybugDB, no Neo4j sidecar.
MCP-native integration: Codex, Claude Code, Cursor, VS Code, Hermes Agent, LangGraph, CrewAI, and AutoGen can use the same memory interface.
Benchmark claims withdrawn (2026-07-03). The prior LongMemEval numbers were withdrawn: they were produced in oracle mode (mean ~1.9 candidate sessions per question, so Recall@5/citation-coverage were ~1.0 by construction, not by retrieval) and the preference-question scores rested on a hardcoded answer table that has since been removed. Zaxy does not currently publish a LongMemEval score. A real, full-haystack LongMemEval run is planned; until it lands, treat the earlier
0.956/0.910/1.000figures as retracted. The Harvey LAB claim is pending the same audit.
Related MCP server: Lians Agent Memory
Quick Start
Install, init, verify
pipx install zaxy-memory
zaxy init
zaxy memory log --eventloom-path .eventloom --limit 5
zaxy memory bootstrap --eventloom-path .eventloom
zaxy doctor --eventloom-path .eventloomThe PyPI distribution is zaxy-memory; the import package and console command
are still zaxy. Bare zaxy init sets up the local embedded graph posture,
repo-local profile, deterministic capture config, genesis event, heartbeat, and
MCP guidance. For Codex, the printed activation launcher starts the managed
capture watcher when the local capture config is present; pass --capture start
only when you want init itself to start the watcher before opening Codex. The
default human output is compact and action-first; add --verbose when you need
the full setup diagnostics, optional checks, fallback commands, resume guidance,
and notes.
For automation, zaxy init --json keeps the raw onboarding fields and adds
setup.status, setup.issues, setup.pending, readiness.status,
readiness.reasons, readiness.actions, and structured
readiness.action_items for both commands and non-command review tasks. Each
structured action carries label, command, original source, and hints
for compact-output tips such as activation <task> replacement and path-stable
command guidance. Installers can render those tips without parsing prose. It also
includes setup.summary, readiness.summary,
readiness.required_action_count, and readiness.reason_count, so client UIs
can render compact status without parsing human output. It also
separates readiness.blocking_diagnostics from
readiness.non_blocking_diagnostics so scripts can distinguish setup
completion, required actions, and advisory doctor warnings before relying on
live memory.
For Codex, zaxy init --codex-mcp-install auto is the default. It writes or
reuses the user-level Codex MCP config when that can be done without replacing
an existing zaxy server entry. If no safe config target exists, it prints the
copyable codex mcp add command. If an existing zaxy entry differs, it asks
you to review that config before replacing it because Codex can silently replace
servers with the same name. Use an explicit mode when you need to force one side
of that decision after review:
zaxy init --codex-mcp-install user
# or: zaxy init --codex-mcp-install commandBoth Codex paths keep the server workspace-neutral. After init, start or
restart Codex through the printed zaxy activate codex ... --launch command so
the MCP server list and Zaxy activation packet are loaded together. The printed
command includes explicit --eventloom-path and --workspace-root values, so
it still targets the initialized repo when copied from another shell.
Run the single-agent memory example:
python examples/single_agent_memory.pyYour local data lives under .eventloom/ as one append-only JSONL file per
session.
For Claude Code instead of Codex:
zaxy init . --domain my-project --preset local-claude --infra checkFor Hermes Agent:
zaxy ide-config hermes --installFor repository development, use pip install -e ".[dev]", ./scripts/setup.sh,
and zaxy status. Start Docker sidecars only for integration tests or explicit
backend comparisons. Production setup writes Docker secret files under
./secrets/; see docs/deployment.md.
Architecture
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 also includes an observe-only OpenAI-compatible packet analyzer for model
call provenance. It forwards packets to one configured upstream endpoint and
records llm.packet.completed events to Eventloom without acting as a router.
See LLM Packet Analyzer.
Public Site and Documentation
Public static site:
site/index.htmlWhy Zaxy:
docs/why-zaxy.mdGetting started:
docs/getting-started.mdMCP quickstart:
docs/mcp-quickstart.mdArchitecture:
docs/architecture.mdConfiguration:
docs/configuration.mdMCP interface:
docs/mcp.mdMemory export contract:
docs/export-contract.mdEventloom contract:
docs/eventloom.mdGraph schema:
docs/graph-schema.mdRetrieval:
docs/retrieval.mdBenchmarks:
docs/benchmarks.mdLLM packet analyzer:
docs/packet-analyzer.mdEmbeddings:
docs/embeddings.mdSecurity:
docs/security.mdOperations and deployment:
docs/operations.md,docs/deployment.md,docs/runbook.mdPython API:
docs/api.mdStability commitment:
docs/stability-commitment.mdMigration guide:
docs/migration.mdArchived benchmark iteration notes, release drafts, and research notes live under
docs/archive/,docs/announcements/, anddocs/research/.Contributing:
CONTRIBUTING.md
Key Features
Immutable audit trail: Eventloom append-only JSONL with SHA-256 hash chains.
Bi-temporal graph: Facts have validity windows (
valid_from,valid_to).Hybrid extraction: Rule-based for typed events (60–80% cost reduction), LLM fallback.
Hybrid retrieval: Exact + keyword + vector + graph traversal with configurable fusion weights.
Session sharding: One Eventloom log per agent/session, with a shared graph.
MCP-native: Drop-in memory for any MCP-compatible agent framework over stdio or SSE.
Observable: Optional Pathlight traces, breakpoints, and diff support via
zaxy-memory[pathlight].Hardened local defaults: bounded MCP inputs, safe session IDs, no-sidecar embedded graph projection, and optional admin token support for replay/invalidation.
Project Structure
File | Purpose |
| Eventloom JSONL I/O + hash chain integrity |
| Hybrid extraction engine + rule registry |
| Embedded LadybugDB projection store |
| Optional Neo4j bi-temporal wrapper via |
| Hybrid retrieval router |
| MCP stdio/SSE server |
| Optional Pathlight observability hooks |
| MemoryFabric orchestrator |
| Per-session Eventloom log manager |
| Shared validation and input bounds |
| CLI ( |
Production Secrets
Zaxy supports Docker/Kubernetes-style secret files for sensitive settings:
Variable | Secret-file variant |
|
|
|
|
|
|
Direct environment variables take precedence over their *_FILE variants.
Use docker-compose.prod.yml as the production compose baseline.
Development
Tests first (Karpathy rule). Every public function has a test.
Unit tests mock external services. Integration tests use Docker for optional sidecar backends.
Coverage gate: ≥92% enforced by CI.
Lint/format:
ruff. Types: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 .The full suite must stay at or above 92% coverage before a sprint is complete.
Release Publishing
The PyPI distribution name is zaxy-memory because zaxy is already occupied
on PyPI. Published releases build from GitHub Actions and upload to
https://pypi.org/project/zaxy-memory/ using PyPI Trusted Publishing with
GitHub OIDC. The import package and console command remain zaxy.
Before publishing, run zaxy doctor --release-smoke to verify the package
version, changelog entry, release workflow, tokenless publishing posture, and
dependency-light LangGraph example.
License
MIT
Available Tools
8 toolscontext_assembleC
Assemble replay plus ranked retrieval into a prompt-ready context bundle. memory_checkout, the front door, wraps this assembly with current facts, citations, and a trust contract.
Inputs: query (required), limit, max_tokens, session_id, +2 more.
memory_appendA
Append a typed event to the agent's persistent memory log. Appended state becomes retrievable through memory_checkout, the front door for reading memory back.
Inputs: actor (required), payload (required), event_type (required), thread, +1 more.
memory_capabilitiesB
Discover Zaxy's memory surface: active capabilities, the ambient usage loop, the active tool profile, and which tools remain callable beyond the listed set. memory_checkout is the front door; call this at session start or whenever tool awareness is unclear.
Inputs: session_id, current_task.
memory_checkoutA
The front door to Zaxy memory: call this first, before substantial work, to checkout current, cited, prompt-ready memory state for a session. Start here; every other memory tool is plumbing or power use, discoverable through memory_capabilities.
Inputs: query (required), ref, limit, purpose, +4 more.
memory_feedbackA
After using retrieved context, record whether a memory item was useful, stale, corrected, or reinforced. This closes the loop on context surfaced by memory_checkout, the front door.
Inputs: feedback (required), entity_name (required), entity_type (required), actor, +9 more.
memory_feeling_of_knowingA
Experimental metamemory pre-check: predict whether memory_checkout would likely return something for a query, in roughly a millisecond, from in-memory session state only (no embedding call, no graph query). Returns a non-authoritative verdict (likely | possible | unlikely) with its signal breakdown and raw score. It is a cheap prediction about checkout, never a memory answer or evidence, and its calibration against real checkout outcomes is still being measured — when in doubt, call memory_checkout.
Inputs: query (required), cues, session_id.
memory_invalidateA
Mark a fact as invalid at a given time (bi-temporal update). History is preserved; the correction surfaces in later memory_checkout (front door) results.
Inputs: invalid_at (required), entity_name (required), entity_type (required), admin_token.
memory_queryA
Query the temporal knowledge graph for relevant context. Power use behind the memory_checkout front door: reach for it when you need targeted hits, temporal filters, or pagination rather than a prompt-ready packet.
Inputs: query (required), limit, paged, cursor, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Most tools have distinct purposes, but context_assemble and memory_checkout overlap in functionality since checkout wraps assembly. memory_feeling_of_knowing is clearly experimental and distinct. Descriptions guide usage, preventing major confusion.
Naming is inconsistent: most tools start with 'memory_', but context_assemble does not. Verbs and nouns are mixed (e.g., memory_append vs memory_capabilities), and context_assemble uses noun_verb order instead of verb_noun.
8 tools is appropriate for a memory management system. Each tool covers a core operation (append, invalidate, query, feedback, capabilities, prediction, assembly), without being excessive or sparse.
The tool set covers the memory lifecycle: add (append), retrieve (checkout/query), update (invalidate), feedback, and discovery (capabilities). Missing a dedicated delete tool, but invalidate handles temporal updates. Minor gaps, but core workflows are supported.
Maintenance
Related MCP Connectors
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
Memory, reflection and safety for AI agents. Hosted or local, no vector database.
Persistent memory and knowledge graphs for AI agents. Hybrid search, context checkpoints, and more.
Persistent memory for AI agents. Semantic search, memory graph, W3C DID identity.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceAudit-grade memory backbone for agent teams. Bi-temporal facts (event time + transaction time, with recall(as_of=...) replay), 6-step deterministic retrieval (no LLM in the critical path), conversation ingest with speaker-locked dual-pass extraction, per-tenant Postgres row-level security, and Ed25519-signed provenance. Postgres + pgvector + Neo4j defaults.31 PyPI14MIT

Lians Agent Memoryofficial
AlicenseAqualityCmaintenanceLocal-first bitemporal memory for AI agents with deterministic supersession, point-in-time recall, erasure proofs, and tamper-evident audit history.917Apache 2.0- AlicenseNot gradedqualityCmaintenanceLocal-first, source-grounded memory for AI agents, with citations, bitemporal history, review-gated corrections, and MCP tools for search and recall.4Apache 2.0
- AlicenseNot gradedqualityBmaintenanceProvides local-first persistent memory with a typed knowledge graph and bounded multi-hop retrieval via MCP, letting coding agents and local LLM systems store, search, and recall facts across sessions without hosted services or model dependencies.MIT