zaxy

Zaxy 是一个为 AI 智能体团队设计的生产级记忆系统，核心目标是让智能体的上下文变成可审计的项目记忆网络。它捕获父任务、工作会话、工具观察、带引用的发现、冲突审核、审批包以及已接受的合并回写，形成一份可查询、可回放、可检查的持久历史。

用途

Zaxy 解决智能体“记住发生了什么、引用来源、避免把项目状态变成一堆 Markdown 文件和向量块”的问题。它面向需要收据（receipts）的智能体团队，强调可审计记忆、智能体团队协调和本地优先运行。

主要能力

• 可审计记忆：每个被接受的事实都能回溯到 Eventloom 历史。
• 智能体团队协调：父会话与工作会话保持隔离，直到发现被审核并合并。
• 本地优先运行时：默认使用嵌入式 LadybugDB 图投影，无需 Neo4j sidecar。
• MCP 原生集成：Codex、Claude Code、Cursor、VS Code、Hermes Agent、LangGraph、CrewAI 和 AutoGen 可使用同一记忆接口。
• 不可变审计轨迹：Eventloom 追加式 JSONL，带 SHA-256 哈希链。
• 双时序图：事实具有有效期窗口（valid_from、valid_to）。
• 混合抽取：对类型化事件使用基于规则的抽取（成本降低 60–80%），LLM 作为回退。
• 混合检索：精确 + 关键词 + 向量 + 图遍历，融合权重可配置。
• 会话分片：每个智能体/会话一个 Eventloom 日志，共享同一张图。
• 可观测性：通过 zaxy-memory[pathlight] 提供可选的 Pathlight 追踪、断点和差异支持。
• 加固的本地默认值：有界 MCP 输入、安全会话 ID、无 sidecar 的嵌入式图投影，以及用于回放/失效的可选管理令牌。

使用方式

PyPI 发行包名为 zaxy-memory，导入包和控制台命令仍为 zaxy。

安装与初始化：

• 裸 zaxy init 会设置本地嵌入式图姿态、仓库本地 profile、确定性捕获配置、创世事件、心跳和 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。
• 对 Codex，zaxy init --codex-mcp-install auto 是默认值。它会在不替换现有 zaxy 服务器条目的情况下写入或复用用户级 Codex MCP 配置；若没有安全配置目标，则打印可复制的 codex mcp add 命令；若现有 zaxy 条目不同，会要求先审核再替换。
• 两条 Codex 路径都保持服务器工作区中立。init 后，通过打印出的 zaxy activate codex ... --launch 命令启动或重启 Codex，以便同时加载 MCP 服务器列表和 Zaxy 激活包。

运行单智能体记忆示例：本地数据位于 .eventloom/ 下，每个会话一个追加式 JSONL 文件。

其他集成：

• Claude Code 替代 Codex 的方式。
• Hermes Agent 的方式。
• 仓库开发使用 pip install -e ".[dev]"、./scripts/setup.sh 和 zaxy status。仅在集成测试或显式后端比较时启动 Docker sidecar。生产设置将 Docker 密钥文件写入 ./secrets/。

可选组件：

• 普通安装使用嵌入式 LadybugDB。仅当需要可选 Neo4j sidecar 时安装 zaxy-memory[neo4j]，仅当需要 Pathlight 追踪时安装 zaxy-memory[pathlight]。
• Zaxy 还包含一个仅观察的 OpenAI 兼容数据包分析器，用于模型调用溯源。它将数据包转发到一个配置的上游端点，并将 llm.packet.completed 事件记录到 Eventloom，但不充当路由器。

适用场景

• 需要可审计、可回放项目记忆的智能体团队。
• 需要引用来源、避免项目状态碎片化的智能体工作流。
• 使用 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 分数。计划进行真实的全 haystack LongMemEval 运行；在此之前，请将早前的 0.956 / 0.910 / 1.000 数字视为已撤回。Harvey LAB 声明也待同样审计。
• 生产密钥支持 Docker/Kubernetes 风格密钥文件；直接环境变量优先于其 *_FILE 变体。
• 测试优先（Karpathy 规则）：每个公共函数都有测试。单元测试模拟外部服务，集成测试使用 Docker 进行可选 sidecar 后端。覆盖率门槛 ≥92%，由 CI 强制执行。Lint/格式使用 ruff，类型使用 mypy。
• 发布：PyPI 发行名称为 zaxy-memory，因为 zaxy 在 PyPI 上已被占用。发布版本从 GitHub Actions 构建，使用 PyPI Trusted Publishing 与 GitHub OIDC 上传。导入包和控制台命令仍为 zaxy。发布前运行 zaxy doctor --release-smoke 验证包版本、变更日志条目、发布工作流、无令牌发布姿态和轻依赖 LangGraph 示例。

文档

公共静态站点：site/index.html；Why 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。