{"id":49986237,"url":"https://github.com/syndicalt/zaxy","last_synced_at":"2026-06-11T03:01:29.501Z","repository":{"id":356164558,"uuid":"1231290655","full_name":"syndicalt/zaxy","owner":"syndicalt","description":"Zaxy turns agent work into durable memory: an Eventloom log for audit, hash-linked provenance for replay, a Neo4j temporal graph for reasoning, Memory Checkout for compact context, and MCP tools for model-facing retrieval, capture, and feedback.","archived":false,"fork":false,"pushed_at":"2026-06-04T13:05:36.000Z","size":9943,"stargazers_count":6,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-04T13:12:58.798Z","etag":null,"topics":["ai","ai-agents","ai-memory","llm-tools"],"latest_commit_sha":null,"homepage":"http://docs.zaxy.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/syndicalt.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-06T20:25:45.000Z","updated_at":"2026-06-04T13:05:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/syndicalt/zaxy","commit_stats":null,"previous_names":["syndicalt/zaxy"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/syndicalt/zaxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syndicalt%2Fzaxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syndicalt%2Fzaxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syndicalt%2Fzaxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syndicalt%2Fzaxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/syndicalt","download_url":"https://codeload.github.com/syndicalt/zaxy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syndicalt%2Fzaxy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34180147,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","ai-memory","llm-tools"],"created_at":"2026-05-18T23:06:16.123Z","updated_at":"2026-06-11T03:01:29.495Z","avatar_url":"https://github.com/syndicalt.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Zaxy\n\n**Production memory for agent teams that need receipts.**\n\nZaxy turns agent context into an auditable project memory fabric. It captures\nparent missions, worker sessions, tool observations, cited findings, conflict\nreview, approval packets, and accepted merge-back into one durable history that\ncan be queried, replayed, and inspected.\n\nUnder the hood, Zaxy uses Eventloom append-only JSONL as the source of truth and\nan embedded Kuzu graph projection for local reasoning. It is built for agents\nthat need to remember what happened, cite where it came from, and avoid turning\nproject state into a pile of markdown files and vector chunks.\n\nThe embedded Kuzu graph projection is the default local runtime.\n\nThe plain install uses embedded Kuzu. Install `zaxy-memory[neo4j]` only for the\noptional Neo4j sidecar, and `zaxy-memory[pathlight]` only for Pathlight tracing.\n\n## Why It Matters\n\n- **Auditable memory**: every accepted fact can point back to Eventloom history.\n- **Agent-team coordination**: parent and worker sessions stay isolated until\n  findings are reviewed and merged.\n- **Local-first runtime**: the default path uses embedded Kuzu, no Neo4j sidecar.\n- **MCP-native integration**: Codex, Claude Code, Cursor, VS Code, Hermes Agent,\n  LangGraph, CrewAI, and AutoGen can use the same memory interface.\n- **External benchmark evidence**: on the full Harvey LAB legal-agent memory\n  benchmark, Zaxy scored `0.788` mean criterion pass rate across `10/10` tasks,\n  `+0.184` vs regular/no-memory, `+0.081` vs the article-best task rows, and\n  won `9/10` task comparisons. See\n  [Benchmarks](docs/benchmarks.md#harvey-lab); the published\n  stats artifact is `reports/benchmarks/harvey-lab-memory-ablation/publishable-statistics.md`.\n- **Headline 500 evidence**: the current LongMemEval-compatible checkout\n  diagnostic is a full 500-question run with mean `0.956`, Answer@5 `0.910`,\n  Recall@5 `1.000`, and citation coverage `1.000`. See\n  [Benchmarks](docs/benchmarks.md#headline-500).\n\n## Quick Start\n\n### Install, init, verify\n\n```bash\npipx install zaxy-memory\nzaxy init\nzaxy memory log --eventloom-path .eventloom --limit 5\nzaxy memory bootstrap --eventloom-path .eventloom\nzaxy doctor --eventloom-path .eventloom\n```\n\nThe PyPI distribution is `zaxy-memory`; the import package and console command\nare still `zaxy`. Bare `zaxy init` sets up the local embedded graph posture,\nrepo-local profile, deterministic capture config, genesis event, heartbeat, and\nMCP guidance. For Codex, the printed activation launcher starts the managed\ncapture watcher when the local capture config is present; pass `--capture start`\nonly when you want init itself to start the watcher before opening Codex. The\ndefault human output is compact and action-first; add `--verbose` when you need\nthe full setup diagnostics, optional checks, fallback commands, resume guidance,\nand notes.\nFor automation, `zaxy init --json` keeps the raw onboarding fields and adds\n`setup.status`, `setup.issues`, `setup.pending`, `readiness.status`,\n`readiness.reasons`, `readiness.actions`, and structured\n`readiness.action_items` for both commands and non-command review tasks. Each\nstructured action carries `label`, `command`, original `source`, and `hints`\nfor compact-output tips such as activation `\u003ctask\u003e` replacement and path-stable\ncommand guidance. Installers can render those tips without parsing prose. It also\nincludes `setup.summary`, `readiness.summary`,\n`readiness.required_action_count`, and `readiness.reason_count`, so client UIs\ncan render compact status without parsing human output. It also\nseparates `readiness.blocking_diagnostics` from\n`readiness.non_blocking_diagnostics` so scripts can distinguish setup\ncompletion, required actions, and advisory doctor warnings before relying on\nlive memory.\n\nFor Codex, `zaxy init --codex-mcp-install auto` is the default. It writes or\nreuses the user-level Codex MCP config when that can be done without replacing\nan existing `zaxy` server entry. If no safe config target exists, it prints the\ncopyable `codex mcp add` command. If an existing `zaxy` entry differs, it asks\nyou to review that config before replacing it because Codex can silently replace\nservers with the same name. Use an explicit mode when you need to force one side\nof that decision after review:\n\n```bash\nzaxy init --codex-mcp-install user\n# or: zaxy init --codex-mcp-install command\n```\n\nBoth Codex paths keep the server workspace-neutral. After init, start or\nrestart Codex through the printed `zaxy activate codex ... --launch` command so\nthe MCP server list and Zaxy activation packet are loaded together. The printed\ncommand includes explicit `--eventloom-path` and `--workspace-root` values, so\nit still targets the initialized repo when copied from another shell.\n\nRun the single-agent memory example:\n\n```bash\npython examples/single_agent_memory.py\n```\n\nYour local data lives under `.eventloom/` as one append-only JSONL file per\nsession.\n\nFor Claude Code instead of Codex:\n\n```bash\nzaxy init . --domain my-project --preset local-claude --infra check\n```\n\nFor Hermes Agent:\n\n```bash\nzaxy ide-config hermes --install\n```\n\nFor repository development, use `pip install -e \".[dev]\"`, `./scripts/setup.sh`,\nand `zaxy status`. Start Docker sidecars only for integration tests or explicit\nbackend comparisons. Production setup writes Docker secret files under\n`./secrets/`; see [docs/deployment.md](docs/deployment.md).\n\n## Architecture\n\n```\nAgent (LangGraph / Any MCP Client)\n    |\n    v\nMCP Server — memory_append / memory_query / memory_feedback / memory_replay / memory_invalidate\n    |\n    v\nEventloom (immutable JSONL log)  →  Hybrid Extraction  →  Embedded Kuzu graph\n    |                                                               |\n    +—————— Optional Pathlight traces ———————————————→  Query Router\n                                                              |\n                                                    Hybrid Retrieval\n                                                    (exact + BM25 + vector + traversal)\n```\n\nZaxy also includes an observe-only OpenAI-compatible packet analyzer for model\ncall provenance. It forwards packets to one configured upstream endpoint and\nrecords `llm.packet.completed` events to Eventloom without acting as a router.\nSee [LLM Packet Analyzer](docs/packet-analyzer.md).\n\n## Public Site and Documentation\n\n- Public static site: `site/index.html`\n- Why Zaxy: `docs/why-zaxy.md`\n- Getting started: `docs/getting-started.md`\n- MCP quickstart: `docs/mcp-quickstart.md`\n- Architecture: `docs/architecture.md`\n- Configuration: `docs/configuration.md`\n- MCP interface: `docs/mcp.md`\n- Eventloom contract: `docs/eventloom.md`\n- Graph schema: `docs/graph-schema.md`\n- Retrieval: `docs/retrieval.md`\n- Benchmarks: `docs/benchmarks.md`\n- LLM packet analyzer: `docs/packet-analyzer.md`\n- Embeddings: `docs/embeddings.md`\n- Security: `docs/security.md`\n- Operations and deployment: `docs/operations.md`, `docs/deployment.md`, `docs/runbook.md`\n- Python API: `docs/api.md`\n- Stability commitment: `docs/stability-commitment.md`\n- Migration guide: `docs/migration.md`\n- Archived benchmark iteration notes, release drafts, and research notes live\n  under `docs/archive/`, `docs/announcements/`, and `docs/research/`.\n- Contributing: `CONTRIBUTING.md`\n\n## Key Features\n\n- **Immutable audit trail**: Eventloom append-only JSONL with SHA-256 hash chains.\n- **Bi-temporal graph**: Facts have validity windows (`valid_from`, `valid_to`).\n- **Hybrid extraction**: Rule-based for typed events (60–80% cost reduction), LLM fallback.\n- **Hybrid retrieval**: Exact + keyword + vector + graph traversal with configurable fusion weights.\n- **Session sharding**: One Eventloom log per agent/session, with a shared graph.\n- **MCP-native**: Drop-in memory for any MCP-compatible agent framework over stdio or SSE.\n- **Observable**: Optional Pathlight traces, breakpoints, and diff support via `zaxy-memory[pathlight]`.\n- **Hardened local defaults**: bounded MCP inputs, safe session IDs, no-sidecar embedded graph projection, and optional admin token support for replay/invalidation.\n\n## Project Structure\n\n| File | Purpose |\n|------|---------|\n| `src/zaxy/event.py` | Eventloom JSONL I/O + hash chain integrity |\n| `src/zaxy/extract.py` | Hybrid extraction engine + rule registry |\n| `src/zaxy/embedded_graph_store.py` | Embedded Kuzu projection store |\n| `src/zaxy/graph.py` | Optional Neo4j bi-temporal wrapper via `zaxy-memory[neo4j]` |\n| `src/zaxy/query.py` | Hybrid retrieval router |\n| `src/zaxy/mcp_server.py` | MCP stdio/SSE server |\n| `src/zaxy/trace.py` | Optional Pathlight observability hooks |\n| `src/zaxy/core.py` | MemoryFabric orchestrator |\n| `src/zaxy/session.py` | Per-session Eventloom log manager |\n| `src/zaxy/security.py` | Shared validation and input bounds |\n| `src/zaxy/__main__.py` | CLI (`zaxy serve`, `zaxy replay`, etc.) |\n\n## Production Secrets\n\nZaxy supports Docker/Kubernetes-style secret files for sensitive settings:\n\n| Variable | Secret-file variant |\n|----------|---------------------|\n| `NEO4J_PASSWORD` | `NEO4J_PASSWORD_FILE` |\n| `MCP_ADMIN_TOKEN` | `MCP_ADMIN_TOKEN_FILE` |\n| `PATHLIGHT_ACCESS_TOKEN` | `PATHLIGHT_ACCESS_TOKEN_FILE` |\n\nDirect environment variables take precedence over their `*_FILE` variants.\nUse `docker-compose.prod.yml` as the production compose baseline.\n\n## Development\n\n- **Tests first** (Karpathy rule). Every public function has a test.\n- **Unit tests** mock external services. **Integration tests** use Docker for optional sidecar backends.\n- **Coverage gate: ≥92%** enforced by CI.\n- **Lint/format**: `ruff`. **Types**: `mypy`.\n\n```bash\n# Run full suite with coverage gate\npytest\n\n# Run integration tests (requires Docker)\n./scripts/generate-certs.sh .certs\ndocker compose --profile integration up -d neo4j-test neo4j-tls\npytest -m integration --no-cov\n\n# Lint and type-check\nruff check src tests\nmypy src\n\n# Current full-set LongMemEval-compatible checkout evidence:\n# reports/benchmarks/longmemeval-500-publish-20260607/\n# Mean 0.956, Answer@5 0.910, citation coverage 1.000, R@1/R@5/R@10 0.960/1.000/1.000.\n\n# Stage the next full 500 only after docs/report cleanup is complete.\nzaxy benchmark --output-dir reports/benchmarks/longmemeval-500-next \\\n  --embedding-provider hash --workload longmemeval \\\n  --dataset .cache/zaxy/benchmarks/longmemeval_oracle.json \\\n  --runs 1 --limit 5 --baseline-backends bm25 \\\n  --projection-backend embedded --zaxy-backend checkout\n\n# Harvey LAB external memory-ablation comparison\n# Consumes externally generated Harvey normalized-result artifacts for Zaxy;\n# does not reuse LongMemEval statistics as legal-agent benchmark evidence.\n# Current full external Harvey LAB evidence:\n# reports/benchmarks/harvey-lab-memory-ablation/publishable-statistics.md\n# reports/benchmarks/harvey-lab-memory-ablation/harvey-lab-benchmark.json\n# 10/10 tasks, mean criterion pass rate 0.788, +0.184 vs regular/no-memory,\n# +0.081 vs article-best task rows, 9/10 wins vs article-best rows.\n\n# Production deployment preflight\nscripts/validate-deployment.sh --root .\n\n# Build and validate Python release artifacts\nscripts/build-dist.sh --root .\n\n# Verify local release metadata, PyPI Trusted Publishing, and LangGraph smoke\nzaxy doctor --release-smoke\n\n# Validate public site and documentation links\nscripts/validate-docs.sh --root .\n\n# Clean-repo beta UAT: install into a throwaway workspace and verify init,\n# bootstrap, deterministic capture, doctor, and memory checkout.\nscripts/beta-uat.sh\n\n# Summarize beta readiness gates without external services.\nzaxy doctor --beta-readiness\n\n# Go-live release gate\nscripts/release-check.sh --root .\n```\n\nThe full suite must stay at or above 92% coverage before a sprint is complete.\n\n## Release Publishing\n\nThe PyPI distribution name is `zaxy-memory` because `zaxy` is already occupied\non PyPI. Published releases build from GitHub Actions and upload to\n\u003chttps://pypi.org/project/zaxy-memory/\u003e using PyPI Trusted Publishing with\nGitHub OIDC. The import package and console command remain `zaxy`.\n\nBefore publishing, run `zaxy doctor --release-smoke` to verify the package\nversion, changelog entry, release workflow, tokenless publishing posture, and\ndependency-light LangGraph example.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyndicalt%2Fzaxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsyndicalt%2Fzaxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyndicalt%2Fzaxy/lists"}