ax 是一个面向 AI 编码智能体的可观测性与记忆层，定位为「智能体体验层（agent experience layer）」，主要服务于 Claude Code 和 Codex 等编码智能体。其核心理念是：让智能体跨会话记住发生过的事情，把每一次会话转化为下一次运行的改进依据。
【解决的问题】 每个子智能体完成工作后即消失，它发现的失败命令、关键文件、应避免的做法也随之丢失，下一个子智能体或下一次会话只能重新摸索。ax 通过观察每次会话、发现重复出现的错误与摩擦，将其转化为针对具体代码仓库的小型修正建议，供用户逐条审核并应用。
【主要能力】
- 统一图谱：将 Claude Code、Codex、Pi、Omp、OpenCode、Cursor 六种 harness，以及已安装技能、本地 git 历史、GitHub PR 及其评审与检查状态，统一摄入一张本地图谱，包含会话、回合、工具调用、计划、技能、提交、文件、摩擦、压缩、派生信号等。摄入采用分阶段管线，未变化的来源会被跳过；读取时会为过期图谱在后台静默执行追赶式摄入。所有数据均为用户磁盘上的文件，无网络往返、无第三方、无服务器。信号在不同 harness 间归一化，例如「上下文耗尽被摘要」无论来自 Claude Code 还是 Codex，都对应同一个可查询的压缩事件。
- 会话回忆：基于 BM25 的全文检索，可在回合、提交、技能中毫秒级本地搜索历史会话。
- 技能评估：对过去 30 天内所有已安装技能给出综合评分，识别哪些技能真正发挥作用、哪些从未触发、哪些与卡住的会话相关；同时统计哪些工具失败最频繁。ax insights 提供 31 个只读图谱视图。
- 成本核算：通过模型定价行解析 token 成本，覆盖提示、输出、缓存读写及估算美元金额，可按会话、文本、提交或分支查询，回答「这次重构花了多少钱」。
- 成本路由：衡量昂贵模型在机械式子智能体工作上的浪费，在派发时给出提醒（route-dispatch hook），提供 efficient-dispatch 技能（通过 npx skills add Necmttn/ax 安装）教授编排模式，ax improve recommend 在缺失节省累积时给出提案，ax routing tune 从派发历史中挖掘新的路由类别（判断类工作不会被自动路由，需通过 --emit-brief 人工审查）。路由表单一事实来源为 ~/.ax/hooks/routing-table.json。
- 会话分享：将完整会话（子智能体记录、harness 钩子触发、逐回合定价）导出、脱敏后发布为 GitHub Gist，并通过托管查看器呈现统一工具调用卡片、会话时间线与成本轨，以及供链接预览使用的会话海报图。数据保留在用户自己的 Gist 账户中。
- Studio 仪表盘：ax studio 基于已发布快照打开仪表盘，按设计是临时的——仅在浏览器连接期间占用端口，之后自行退出，无守护进程需要启动、查找或停止。包含转录视图（工具调用与结果合并为一张卡、技能与图像回合折叠、子智能体派生及其指标）、会话时间线、会话画布（会话与其子智能体的语义缩放谱系图，支持泳道、最高 2000 倍时间轴缩放、约 30ms 悬停详情）、实时摄入（可从仪表盘触发运行并流式查看阶段，中途刷新可续）、指标（ax sessions metrics、ax signals 呈现图谱派生的会话健康度，如脆弱级联、计划变动、工具重试；ax sessions compare 并排比较两次运行）、harness doctor（对配置实际效果打分，每应用一项修复即提升分数）。
- 落地到智能体文件：ax 基于用户自身会话证据，建议对 AGENTS.md / CLAUDE.md / skills 的修改，并追踪哪些行来自它；每个提案附带证据链（ax improve show <id>），判定结果落在会话数窗口上。
- 自定义守卫：用类型化 TypeScript 编写一次钩子，在自有历史上验证，并在 Claude Code 与 Codex 中运行。
- 会话中查询：推荐智能体循环为工作前执行 ax project context --json（获取技术栈、近期摩擦、验证命令），工作后执行 ax project verify --json；Codex 用户可在 ~/.codex/config.toml 中添加 ax mcp。
【使用方式与依赖】 需要 Bun ≥ 1.3。无需数据库服务器：图谱是嵌入的 DuckDB 文件加一个用于记录决策的小型 SQLite sidecar，因此无需安装、启动或连接任何东西。以 macOS 优先；Linux 可用于摄入与 CLI（唯一可选的 launchd 智能体是遥测接收器）。开发安装、schema、查询、基准测试见 docs/development.md。此外，可直接把安装提示粘贴进 Claude Code / Codex，由智能体自行安装 ax、摄入历史、标注技能，并告知哪些技能值得使用；也可对图谱发起此前无法提出的查询。
【适用场景】
- 需要跨会话追踪 AI 编码智能体行为、失败模式与技能有效性的开发者。
- 需要对智能体工作做 token 成本核算与路由优化的团队或个人。
- 希望将历史会话证据转化为 AGENTS.md/CLAUDE.md 与技能改进的工程实践。
- 需要分享、复盘某次艰难会话的开发者。
【限制与许可】 工具为本地优先，无网络往返；macOS 优先，Linux 支持摄入与 CLI。判断类工作不会被自动路由。数据保留在用户自己的磁盘与 Gist 账户中。采用 AGPL-3.0-only 许可，© 2025 Necmettin Karakaya；AGPL 不允许的用途可获取商业许可。定价、具体收费、效果数据、平台支持范围等更多细节暂未在资料中提供。
