数据存储

kxen 采用本地优先存储，当前没有 kxen 云同步服务。

目录

~ 由操作系统解析为当前用户主目录，macOS、Linux 和 Windows 使用相同的 .agents/kxen 相对布局。KXEN_DATA_DIR 可以显式选择 custom 用户根目录；配置、数据和缓存会一起切换，不会再分散到平台专用目录。

Kxen 不会自动读取、移动或删除旧目录中的数据。升级后从新的统一目录开始读写；旧目录的保留、备份或清理由用户显式决定。

kxen-agent 默认使用 ~/.agents/kxen/agent/ 作为独立 state root，可以用 KXEN_AGENT_STATE_DIR 或每次调用的 --state-dir 覆盖。它复用用户配置和 auth store 的默认位置，但不会把 provider credential 复制到 agent state。

用户配置

• config.toml: 路由、限制、实验开关和一般设置。
• mcp.json: 用户级 MCP server 配置。
• custom-provider.transaction.json: 只在 custom Provider 的配置和凭证跨文件提交尚未完成时存在的恢复 journal。

项目可以提供 .agents/kxen/config.toml 和 .mcp.json。只有受信任 Workspace 的项目配置和项目 MCP 才会加载。

应用数据

• workspaces.json: 最近 Workspace。
• sessions/: Session meta、消息、队列、compaction、artifact、删除 tombstone 和 recovery bundle。
• goals/: Goal contract、状态和预算用量。
• teams/: Team 配置、任务、inbox 和 member transcript。
• bots/: Bot definition、immutable revision、Builder Session、BotRun、Conversation、Routine、Memory、Artifact 和 Recovery event stream。
• auth.json: Provider 凭证。
• mcp-oauth.json: MCP OAuth token、refresh token 和 client secret，按 scope + server 名 + canonical resource endpoint 绑定。
• trusted.json: Workspace 信任记录。
• credential-consent.json: 本机凭证来源授权。
• notifications.json: 最近通知。
• schedule.json: Schedule 和 durable dispatch 状态。
• usage.json: Session 和 system_* 全局付费操作的已知 token 下界与 UNKNOWN 计数。system scope 纳入总量和完整性，但不计入产品显示的 Session 数量。
• usage-trend.json: 最近 90 天按日期和 Provider 的 usage。
• usage-attempts/: 已跨过或准备跨过 Provider 边界的 durable usage attempt。启动恢复先结算或标记 UNKNOWN，不会按 0 丢弃。
• workflow-journals/: Dynamic Workflow 恢复 journal。
• shadow/: Checkpoint 的独立 Git repository。
• models-catalog.json: Provider 模型目录缓存。
• embedding-cache.json: Knowledge embedding cache。
• composer-suggestions/<workspace-hash>/embedding-cache.json: 用户显式启用 Composer semantic suggest 后生成的 Workspace 隔离向量缓存。
• consolidate.json: Knowledge consolidation watermark。
• consolidation-attempts/: Knowledge 蒸馏的 Provider attempt、消息 revision、cursor、候选 Note 和写入进度。每个 attempt 同时保存可解释的 status 和 reason；provider_result_unknown 会阻止自动重试，直到用户显式确认 UNKNOWN。
• knowledge-moves/: 项目与个人 scope 移动的私有 transaction claim；项目内容不能提供或修改该 claim。
• instance.lock: 单实例持有的进程锁。

Agent state

kxen-agent state root 的 sessions/ 保存 core Session meta 与 JSONL、<session_id>/dcp/session.json、每个 <run_id>/run.json 和 tools.json。.locks/ 保护跨进程 Session mutation，.run-locks/ 保证同一 Session 只有一个执行者。usage-attempts/、tool-home/、mcp-launch-audit.jsonl 和每个 run 的 Shell audit 分别保存 provider attempt、隔离工具 home 和非交互授权审计。

session export 生成自包含 JSON bundle，包含消息、DCPAgent lock、DCPRun 与 tool journal，不包含 auth store、API key、外部 CLI token 或 OS credential。state 和 bundle 仍可能包含任务正文、代码上下文及工具输出，应作为私有数据保存。

这些文件的真源、重建和 UNKNOWN 语义见 DCP。

Session

每个 Session 使用 <id>.json meta 和 <id>.jsonl 消息文件，并可以包含 <id>.compact.json、<id>.queue.json 与 <id>/ artifact 目录。消息追加写入，meta 和需要重写的状态使用临时文件、fsync 和 rename。meta 中的单调 message_revision 在真实 append 或 rewrite 后推进；同 ID、同内容的幂等 append 不会虚增 revision。

分支 Session 的 meta 还保存 parent_id、稳定的 branch_root_id、fork_kind 和 fork_point。fork_point 包含父 Session 的 Message ID、从 1 开始的序号、创建时间，以及 before 或 after 位置。根 Session 和旧格式可以缺少这些字段。删除父级不会改写或级联删除后代，后代保留原谱系 ID，等待父级从系统废纸篓恢复。

Session 可以包含文本、隐藏上下文、工具调用、推理、图片和 Approval 结果。图片以内联数据保存，使 fork、导出、rewind 和删除保持自包含。Fork 使用严格读取和 staging，复制的消息拥有新 ID，meta 最后发布为 admission marker，因此部分写入不会进入 Session catalog。Queue delivery 同时持久化稳定 ID 和原始 created_at；一旦用户消息写入 JSONL，重放直接复用该消息中的文本、已解析上下文和图片，不重新读取可能变化的文件或 URL。

Markdown 分支导出包含 branch root、parent、fork point、fork kind 和 workspace-state: shared-current。该标记说明分支只隔离对话状态，不保存或复制 Workspace 文件。

sessions/.deleted/ 保存删除 tombstone、本地 recovery bundle 和传输 backup。进入系统废纸篓的 <id>.kxen-session bundle 可从废纸篓恢复，再由启动扫描导入。

sessions/.recovery/ 保存存储一致性修复前的原始 JSONL 字节证据，格式为 <id>.messages.<uuid>.bak。目录权限为 0700，备份权限为 0600。这些文件不是普通缓存；确认不再需要恢复或核对前不要删除。

存储恢复契约

当前 Session 的 Composer 上方会自动调用 recovery.inspect。健康时面板隐藏；检测到 JSONL 尾部问题、Session PostCommit 写入阻塞或 PendingQueue 阻塞时，面板显示两个 store 的状态。

• recovery.inspect 只读检查 Session meta、compaction、messages 和 queue，返回 healthy、repairable_tail、corrupt 以及是否可证明恢复。
• recovery.repair 要求没有 active run，且 Session 和 Queue 都可恢复。如存在可修复的 JSONL 尾部，它会先完整备份原 JSONL；随后修复可证明的最后尾部、meta floor 和精确的 PostCommit 持久化状态，对可见文件和父目录 fsync 后才清除阻塞。
• recovery.clear 只在 JSONL 已经健康时调用同一套精确验证和 fsync 逻辑，用于解除可证明的 PostCommit block。它不是强制忽略损坏的开关。
• JSONL 中间损坏、身份冲突、Queue 文件解析失败或盘上 Queue 与内存期望快照不同时 fail closed。恢复 API 不会删除原文件或猜测数据。

用户不需要手工调用这些 RPC。面板会在可修复尾部操作前要求二次确认，修复失败时保留原文件、备份和阻塞状态。

Goal 和 Team

Goal 保存在应用数据的 goals 子目录。完成判定的 operation ID、contract/evidence identity、阶段、结果和 usage receipt 直接保存在对应 Goal JSON 中。Team 配置、共享任务、inbox 和 member transcript 保存在 teams 子目录。

Bot 的所有 aggregate 和 Artifact 都位于应用数据的 bots/ 子目录。Run、Conversation、Routine 和 Recovery 使用各自的 durable identity 和 event stream；这些文件不是普通缓存，不要通过手工删除来跳过 blocked 或 UNKNOWN 状态。使用应用中的 Recovery Center 核对和处理。

凭证

Provider 认证数据保存在权限受限的 auth.json，MCP OAuth 数据保存在权限受限的 mcp-oauth.json。二者都是本地 JSON，不是 macOS Keychain。配置文件只保存路由或连接描述，不保存 API key、OAuth token、refresh token 或 client secret。

认证文件不得提交到 Git。复制或删除认证数据前先退出应用，并确认目标文件权限。

Checkpoint

Checkpoint 使用独立 shadow Git repository，不写入 Workspace 自身的 .git。

Workspace 中的 .agents/kxen/worktrees/ 保存隔离 Worktree，.agents/kxen/backups/ 保存覆盖前的有限数量恢复副本。项目 .agents/ 保存共享知识，用户 ~/.agents/ 保存个人知识；Knowledge 扫描会明确排除两个 scope 的 kxen/ 子树。跨 scope 移动先在用户级 Kxen 根目录建立 claim，再通过 staging、文件 fsync、rename 和父目录 fsync 提交；跨文件系统时不依赖单次 rename。

Kxen 会在 ~/.agents/.gitignore 中幂等维护 /kxen/，并在 Git Workspace 的 .gitignore 中幂等维护 /.agents/kxen/。Checkpoint、Composer 索引和 Knowledge 扫描也使用同一运行态边界，避免把私有状态加入 Git、检查点或模型上下文。显式 custom root 不会改写其父目录的 ignore 文件。

Knowledge 的 UNKNOWN 确认先把 usage receipt 写入 usage.json，再把可证明的被跳过 cursor 写入 consolidate.json，最后删除 consolidation-attempts/<session_id>.json。启动时的 receipt compaction 会保留仍被任一 Knowledge attempt 引用的 operation ID，因此在 usage 已提交、attempt acknowledgement 尚未提交的 crash window 中重启也不会重复计量。缺少精确 cursor 的 legacy attempt 不推进 watermark。保留 attempt 是故障恢复依据；不要手工删除它来绕过结算。

删除 Session 时，即使选择「不沉淀」，也会在 recovery manifest 捕获之前把 Knowledge blocked attempt 的 UNKNOWN usage 写入 usage ledger。manifest 因此保留完整的已知下界和 UNKNOWN 计数；claim 只在后续关联清理阶段删除。

删除

生产环境中的文件和 Session 删除进入系统废纸篓。清理整个应用数据目录会同时影响 Session、Goal、Team、认证和恢复状态，不能当作普通缓存清理。