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

Zaxy

为需要凭证的 Agent 团队打造的生产级记忆。

Zaxy 将 Agent 上下文转化为可审计的项目记忆网络。它会捕获父级任务、工作会话、工具观察结果、附有引用的发现、冲突审查、审批材料，以及已接受并合并回主线的内容，并将它们汇入一段持久历史，可供查询、回放和检查。

在底层，Zaxy 使用 Eventloom 追加写入式 JSONL 作为事实来源，并使用嵌入式 LadybugDB 图投影进行本地推理。它专为需要记住发生过什么、注明信息来源，并避免将项目状态变成一堆 Markdown 文件和向量分块的 Agent 而构建。

嵌入式 LadybugDB 图投影是默认的本地运行时。

基础安装使用嵌入式 LadybugDB。仅在需要可选 Neo4j 辅助服务时安装 zaxy-memory[neo4j]，仅在需要 Pathlight 跟踪时安装 zaxy-memory[pathlight]。

它为何重要

• 可审计的记忆：每条已接受的事实都可以追溯到 Eventloom 历史记录。
• Agent 团队协作：父级和工作会话彼此隔离，直到相关发现经过审查并合并。
• 本地优先运行时：默认路径使用嵌入式 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，如果存在本地捕获配置，打印出的激活启动器会启动受管理的捕获监视器；只有在希望 init 自身于打开 Codex 前启动监视器时，才传入 --capture start。默认的人类可读输出简洁且以操作为先；需要完整的设置诊断、可选检查、回退命令、恢复指南和备注时，添加 --verbose。 对于自动化，zaxy init --json 会保留原始入门字段，并添加 setup.status、setup.issues、setup.pending、readiness.status、readiness.reasons、readiness.actions，以及结构化的 readiness.action_items，涵盖命令和非命令类审核任务。每项结构化操作都包含 label、command、原始 source，以及用于简洁输出提示的 hints，例如激活时替换 <task> 和路径稳定的命令指南。安装程序可直接呈现这些提示，无需解析说明文字。它还包含 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 值，因此即使从另一个 shell 复制，也仍会指向已初始化的仓库。

运行单 Agent 记忆示例：

python examples/single_agent_memory.py

你的本地数据位于 .eventloom/ 下，每个会话对应一个只追加的 JSONL 文件。

使用 Claude Code 而非 Codex 时：

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 辅助服务。生产环境设置会在 ./secrets/ 下写入 Docker 密钥文件；请参阅 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 兼容数据包分析器，用于追踪模型调用来源。它会将数据包转发到一个已配置的上游端点，并将 llm.packet.completed 事件记录到 Eventloom，但不会充当路由器。请参阅 LLM 数据包分析器。

公共网站和文档

• 公共静态网站：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

主要功能

• 不可变审计轨迹：Eventloom 仅追加 JSONL，并使用 SHA-256 哈希链。
• 双时态图：事实具有有效时间窗口（valid_from、valid_to）。
• 混合提取：对类型化事件使用基于规则的提取（成本降低 60–80%），并提供 LLM 回退方案。
• 混合检索：结合精确匹配、关键词、向量和图遍历，并支持配置融合权重。
• 会话分片：每个 Agent/会话使用一个 Eventloom 日志，共享同一张图。
• 原生支持 MCP：通过 stdio 或 SSE，为任何兼容 MCP 的 Agent 框架提供即插即用的记忆。
• 可观测：通过 zaxy-memory[pathlight] 可选支持 Pathlight 跟踪、断点和差异功能。
• 强化的本地默认设置：限制 MCP 输入、使用安全的会话 ID、嵌入式图投影无需旁路进程，并可选支持用于重放/失效处理的管理员令牌。

项目结构

文件	用途
src/zaxy/event.py	Eventloom JSONL 输入/输出 + 哈希链完整性
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 变体。 使用 docker-compose.prod.yml 作为生产环境 Compose 配置基线。

开发

• 先写测试（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-memory，因为 zaxy 已在 PyPI 上被占用。已发布的版本通过 GitHub Actions 构建，并使用 PyPI Trusted Publishing 和 GitHub OIDC 上传至 https://pypi.org/project/zaxy-memory/。导入包和控制台命令仍为 zaxy。

发布前，运行 zaxy doctor --release-smoke，以验证包版本、变更日志条目、发布工作流、无需令牌的发布配置，以及依赖轻量的 LangGraph 示例。

许可证

MIT