Zaxy

Event-sourced temporal knowledge graph fabric for AI agent memory.

Zaxy replaces markdown files + vector DBs with a structured, replayable, bi-temporal memory system built on Eventloom and an embedded Kuzu graph projection, with optional Neo4j, pgGraph, and Pathlight integrations. The plain install uses embedded Kuzu. Install zaxy-memory[neo4j] only for the optional Neo4j sidecar, and zaxy-memory[pathlight] only for Pathlight tracing.

Quick Start

Five-minute local smoke test

# Install the Zaxy CLI before generating MCP config. The distribution is
# zaxy-memory; the import package and console command remain zaxy.
pipx install zaxy-memory
# or: pip install zaxy-memory

# Initialize local memory, Codex MCP guidance, deterministic capture config,
# profile, genesis, heartbeat, and no-sidecar embedded graph posture.
zaxy init

# Prove the local Eventloom log and model bootstrap are readable.
zaxy memory log --eventloom-path .eventloom --limit 5
zaxy memory bootstrap --eventloom-path .eventloom
zaxy doctor --eventloom-path .eventloom

Your local data lives under .eventloom/ as one append-only JSONL file per session. Bare zaxy init now expands to the local embedded Codex path: it prints the Codex MCP install command, writes .codex/zaxy-capture.json, writes .env.local, checks the repo-local embedded graph posture, and ends with copyable local verification commands. It does not start a background watcher unless you pass --capture start.

For Claude Code instead of Codex:

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

For Hermes Agent:

zaxy ide-config hermes --install

For 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 Kuzu 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.html
Why Zaxy: docs/why-zaxy.md
Getting started: docs/getting-started.md
Architecture: docs/architecture.md
Configuration: docs/configuration.md
MCP interface: docs/mcp.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

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
`src/zaxy/event.py`	Eventloom JSONL I/O + hash chain integrity
`src/zaxy/extract.py`	Hybrid extraction engine + rule registry
`src/zaxy/embedded_graph_store.py`	Embedded Kuzu projection store
`src/zaxy/graph.py`	Optional Neo4j bi-temporal wrapper via `zaxy-memory[neo4j]`
`src/zaxy/query.py`	Hybrid retrieval router
`src/zaxy/mcp_server.py`	MCP stdio/SSE server
`src/zaxy/trace.py`	Optional Pathlight observability hooks
`src/zaxy/core.py`	MemoryFabric orchestrator
`src/zaxy/session.py`	Per-session Eventloom log manager
`src/zaxy/security.py`	Shared validation and input bounds
`src/zaxy/__main__.py`	CLI (`zaxy serve`, `zaxy replay`, etc.)

Production Secrets

Zaxy supports Docker/Kubernetes-style secret files for sensitive settings:

Variable	Secret-file variant
`NEO4J_PASSWORD`	`NEO4J_PASSWORD_FILE`
`MCP_ADMIN_TOKEN`	`MCP_ADMIN_TOKEN_FILE`
`PATHLIGHT_ACCESS_TOKEN`	`PATHLIGHT_ACCESS_TOKEN_FILE`

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: ≥90% 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

# Competitive retrieval benchmark harness
pytest tests/test_competitive_benchmarks.py --benchmark-only --no-cov

# Frozen live benchmark: markdown vs BM25 vs vector vs markdown+vector vs embedded Zaxy
# Uses deterministic hash embeddings and embedded projection by default.
scripts/live-benchmark.sh --workload frozen --runs 1 --reset-graph

# Representative benchmark suite: temporal memory + docs + transcripts + mixed context
scripts/live-benchmark.sh --workload suite --subjects 100 --documents 250 --sessions 50 --runs 1 --reset-graph

# LongMemEval-compatible memory benchmark and BM25 comparison
# Plain benchmark commands use the embedded projection backend by default.
zaxy benchmark --embedding-provider hash --workload longmemeval \
  --dataset .cache/zaxy/benchmarks/longmemeval_oracle.json \
  --questions 100 --runs 1 --limit 10 --zaxy-backend checkout \
  --baseline-backends bm25 --embedding-cache .cache/zaxy/longmemeval-embeddings.json
zaxy benchmark --output-dir reports/benchmarks/longmemeval-100-comparison \
  --embedding-provider hash --workload longmemeval \
  --dataset .cache/zaxy/benchmarks/longmemeval_oracle.json \
  --questions 100 --runs 1 --limit 5 --baseline-backends bm25 \
  --zaxy-backend checkout --reuse-projection \
  --embedding-cache .cache/zaxy/longmemeval-embeddings.json

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

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

# Verify local release metadata and PyPI Trusted Publishing configuration
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 90% 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, and tokenless publishing posture.

License

MIT