Repository navigation
[Feature]: explicit revision-guarded cross-agent session continuation #4085
Description
Problem or unmet outcome
When a developer switches from one coding agent to another (e.g. Claude Code to Codex), the target agent has no structured way to receive what the source agent was working on — what was done, what was tried and failed, what comes next. The developer must re-explain the entire project state.
LoopX's existing handoff_note on todos is a static snapshot with no structured context, no discovery, and no resume semantics. The claimed_by + handoff_mode ownership model governs Todo claims but provides no protocol for cross-agent context transfer.
What Stage A delivers (PR #4094)
A bounded, explicit handoff workflow over the canonical Todo authority. The source agent consciously prepares a structured continuation note; the target agent inspects, verifies, and adopts the Todo with full context.
Capabilities
- Rich handoff context: structured fields (
work_summary,approaches_tried,next_steps,files_touched,key_decisions,open_questions) so the target agent gets a complete picture --from-contextCLI flag: agents dump structured context from a JSON file--format digestCLI output: renders a readable handoff summary for any target agent- Typed
transfer_grant(todo_transfer_grant_v0): binds source/target/todo/revision/note facts for scoped cross-agent authority — only the handoff flow can produce this grant; regularloopx todo claimstill rejects foreign-owner Todos withclaim_owner_mismatch - Shared
continuation_note.tsmodule: single source of truth for note validation, used by both handoff helper and final claim authority - Backward compatible: legacy
rationale+source_refsstill work
CLI usage
# Source: prepare rich handoff context from JSON
loopx handoff prepare --goal-id demo --todo-id todo_a \
--agent-id agent-a --session-id source-session --operation-id handoff-1 \
--expected-revision "$REVISION" --from-context ./handoff-context.json
# Target: inspect with readable digest
loopx handoff inspect --goal-id demo --todo-id todo_a \
--agent-id agent-a --session-id target-session --workspace . --format digest
# Target: adopt the Todo
loopx handoff adopt --goal-id demo --todo-id todo_a \
--agent-id agent-b --session-id target-session --operation-id resume-1 \
--expected-revision "$REVISION" --target-agent-id agent-b --workspace .Prerequisites
- An explicitly promoted local file authority
- An open, active agent Todo claimed by a registered agent
- No lease on that Todo
- Both agents registered under the same goal (
peer_v1agent model)
What Stage A does NOT solve
This is a manual, explicit handoff flow. It does NOT:
- Automatically capture agent context. The source agent must consciously prepare the continuation note. LoopX is a control plane, not an agent runtime — it cannot automatically extract Claude Code's internal state (conversation history, reasoning chains).
- Provide agent-agnostic context format. The continuation note is a LoopX-specific schema. A non-LoopX agent cannot directly consume it without understanding the format.
- Support zero-config onboarding. The target agent must know to run
handoff inspect, have the right registry/runtime arguments, and be a registered agent. - Enable real-time session bridging. The source must stop execution before the target can adopt. No live collaboration or concurrent editing.
- Replace run_history or reward_memory. This is a handoff primitive, not a general memory system.
Use cases addressed
- Same-machine agent switch. Agent A (Claude Code) finishes a research slice, prepares a handoff note, and Agent B (Codex) continues the implementation with full context.
- Session migration (manual). User explicitly hands a Todo from one session to another on the same host, transferring both ownership and decision context.
- Cross-agent task routing. Agent X hands findings to Agent Y with structured context about what was tried and what's next.
Use cases deferred (require different product layer)
- Implicit context capture. Automatically extracting what an agent "knows" without explicit user action — requires agent-runtime integration, not a control-plane primitive.
- Agent-agnostic handoff. A format any agent (LoopX or not) can produce/consume — requires a shared protocol beyond LoopX's Todo authority.
- Multi-host session migration. Syncing context across machines — requires merge-aware state sync, not just a handoff flow.
- Memory discovery / semantic search. "What was the last session working on?" — requires indexing and query infrastructure.
- Memory lineage / supersedure chains. Tracking context evolution across multiple handoffs — requires a memory graph, not a single transfer.
Scope and non-goals
In scope (Stage A):
- Continuation note schema (rich structured fields)
- Revision-guarded prepare/inspect/adopt workflow
- Typed
transfer_grantfor scoped cross-agent authority - CLI:
handoff prepare,handoff inspect,handoff adopt --from-contextinput flag,--format digestoutput- Integration with existing
claimed_by+handoff_modeownership
Out of scope (deferred to future stages):
- Automatic context capture from agent runtimes
- Agent-agnostic context format
- Cross-host sync or merge semantics
- Memory discovery, indexing, or semantic search
- Memory lineage or supersedure graph
- Vector database or external embedding service
- Real-time session bridging or live collaboration
- Migration of run_history data into memories
LoopX area
Control plane (goals, todos, coordination, CLI)
Related
- PR feat(todos): explicit revision-guarded cross-agent session continuation (Stage A) #4094 — Stage A implementation (rich handoff context + digest output)
Activity
xiaods commentedon Sep 8, 2026
docs(rfc): add cross-session memory substrate v0 RFC (EN + ZH)
docs(rfc): add cross-session memory substrate v0 RFC (EN + ZH)
huangruiteng commentedon Sep 8, 2026
@xiaods，跨会话接续这个方向值得做：新会话需要知道「现在做到哪里、为什么这样做、哪些证据仍有效」，才能减少重复探索并可靠接手。你把这个问题从会话体验推进到产品能力，是有价值的。针对 #4094，我进一步看了现有 LoopX 边界和 9 个外部候选，重点读了 Obelisk、OpenViking、coding_agent_session_search 的实现。
我的建议是保留这个目标，先调整实现分工：LoopX 负责当前执行状态与接管，历史检索和长期记忆通过可选 provider 复用基建；第一阶段交付一个真实可用的接续流程。 暂时不宜把另一个通用 memory store、索引、发现、恢复和所有权协议一起固化进 core。以下是源码与官方文档调研结论；没有对这些项目做部署压测或同题效果评测，因此候选优先级是待验证的工程判断。
1. 先分清四种不同的能力
记忆中写着「A 正在处理」不能替代实时 ownership；一份摘要也不能恢复不存在的 worktree。跨机器可读到同一条记录，只解决了数据可见性，还没有解决执行现场和接管权限。
2. 三个重点候选：具体复用什么
Obelisk：优先验证的本地会话证据层
这里指 tommy0103/obelisk。它已经在做多来源会话规范化、本地 SQLite/FTS5 索引、查询和人工浏览。
最值得复用的并不只是搜索框，而是增量摄取契约：Provider 分开
discover与parse，通过稳定的 IndexUnit key、cursor 和 TranscriptRecord 处理来源差异；有明确的可见性与来源撤回语义，可以区分有效记录、被替代分支及隐藏内容。索引写入与游标提交放在事务里，并报告摄取不完整的情况。这些细节正是自建 JSONL + 扫描索引后容易不断补课的地方。Provider 类型、索引提交建议做一个可选 adapter，输入明确的 goal/repo/host/session 范围与检索预算，输出有来源定位、时间和完整性状态的少量证据，再按需读取原文。避免把内部数据库 schema 变成 LoopX 的长期契约，也不要将任意 SQL/JS 查询直接暴露成跨租户接口。来源目录应显式配置，不能安装后自动扫描所有宿主历史。
它的 writer lease 用于保护本地索引写入，不是 LoopX 任务 lease。它不会替我们实现 Todo 接管、workspace 恢复或多主机同步。当前许可证为 AGPL-3.0-only，分发方式需要单独评估。writer lease、LICENSE
coding_agent_session_search / CASS：更完整的会话检索与证据打包候选
CASS 已有多种 coding-agent 来源接入、词法/语义检索、机器可读 CLI、按源位置
view/expand，以及紧凑的pack证据包。适合比较「检索后给接续 agent 什么」：先少量返回命中，再按需展开，而不是一次灌入整个 transcript。源码中的 pack planner 会核对来源引用、在截断前脱敏，并携带 freshness / evidence 问题；会话身份也考虑了
source_id + agent_id + external_id，值得借鉴，避免两台机器出现同名 session 时串数据。注意max-tokens是近似预算，需要 LoopX 自己保证最终模型上下文上限。pack planner、存储身份两点需要在选型前看清：第一，不应因为项目出现 swarm/workpacket 等名字，就认为已有生产可用的协调系统；当前 README 明确把部分 swarm 接口描述为 fixture-based，不能据此替代 LoopX authority。第二，当前 LICENSE 标题是 “MIT License (with OpenAI/Anthropic Rider)”，附有针对特定主体及相关使用的额外限制，不能直接归类为普通 MIT 后内置或复制代码；具体集成、使用和分发要先澄清适用条款，外部进程调用也不是自动豁免。README、完整许可证
工程上建议把它作为 Obelisk 的对照候选，在许可明确后比较接入成本、来源覆盖、引用可回读性和检索收益。无需把整个工具集合都引入 LoopX；模型安装和语义搜索应显式启用，检索不可用时要给出可诊断的降级结果。
OpenViking：复用已有接入，承接上下文组织与经验沉淀
OpenViking 更接近持续上下文与记忆基础设施：
viking://组织 resources、memories、skills，L0/L1 摘要与 L2 原文支持分层读取，session commit 能归档会话并异步提取记忆。它适合长期可检索上下文、经验归纳及更新，不只是另一种全文搜索。上下文分层、session 生命周期实现上，session append/commit 共用会话路径锁，commit 包含归档、任务入队和后续处理阶段。因此
accepted/task_id不等于记忆已可检索；adapter 应区分 accepted、pending、ready、failed/partial。记忆隔离也有 RequestContext、self/peer 范围和写入目标检查，不能把一个 peer 标识直接当作授权。session 实现、记忆隔离LoopX 已有 OpenViking 扩展和 context/reward-memory 接口，优先补这条路径。不要为了这次接续再创造一套独立 OV 接入体系。普通 handoff 应在提取服务离线时仍可执行；只有明确的经验沉淀才进入异步记忆处理。历史中的临时 blocker、失败尝试和过期决定也不应自动升级为未来任务的规则。
代价是存储服务、模型配置、提取延迟与运维；本地部署不能自动保证配置的 LLM/embedding 不调用外部服务。当前 AGPL-3.0 许可也应纳入分发评估。只有小实验能证明收益，才能决定是否启用，而不能把「具有记忆功能」当作接续效果的证明。检索机制、许可证
3. 另外六个也看了，但不建议全部接入
选型需要比较的是我们还要维护多少 glue code、多少新状态和故障路径，以及来源能否可靠回读，而非功能列表或 stars。上述源码快照固定了本次判断范围，不能据此保证未来版本行为不变。
4. LoopX 内部已有可复用边界
目前「reward memory 只负责偏好」这个前提不完整。现有文档已经区分
fresh_execution_context和 revision-bound 的session_working_memory，并将它们放在working_context下；handoff_note_v0也已有 intent、evidence refs、blocker、unresolved decisions 等信息。需求依然成立，但缺口更像是生产者、触发时机和接续消费链路尚未形成，而不是缺少所有基础数据类型。reward-memory、现有 handoff noteContextProvider已表达 resource ref、summary/content、retrieval status、版本、延迟和 readiness；decision-context 已有 goal/agent/context-scope 受限的单次 recall，以及「外部内容不可作为指令」的边界。可以复用这些结构与 optional provider 生命周期，不必让简单 handoff 被迫走完整 decision settlement。Provider 接口、decision-context建议落位：接续 briefing/proposal 属于现有 Todo handoff 与 working-context 的协作流程；只读检索经过现有 context-provider seam；Obelisk/CASS 的可选实现走扩展生命周期，需要独立分发时用独立 package；长期经验继续由 reward-memory 及其 provider 管理。是否需要新的 provider-neutral capability，等第一个真实调用方提出稳定契约后再定。
5. 可交付的阶段安排
阶段 A：无新增基建依赖，先跑通一次真实接续。 选择一个确实存在的宿主入口，例如用户显式 handoff 后在目标会话接续同一 Todo。源侧保存无法从当前状态重建的决定理由和来源引用；目标侧读取当前 Todo/goal/revision、精简交接说明和 workspace/artifact 可用性，输出带证据的下一步建议；实际接管仍调用现有 claim/lease 边界，并回读结果。Todo 必须保留稳定 ID，不能只用文本另造一个 Todo。已经完成、被别人接管、revision 改变时，应重算或拒绝接管。
这个阶段需要明确「谁在什么事件产生记录」「缺少记录怎么办」「谁使其过期」，并验证正常重启和中途失败。先把一个完整流程做好，再用它倒推最小 schema；不要先冻结涵盖所有未来场景的 v0。
阶段 B：只选择一个历史证据 provider 做可选增强。 先验证 Obelisk；许可明确后与 CASS 对照。固定 query/read adapter，显式绑定来源、viewer 范围和预算；结果保留可回读引用、observed revision/time、完整性及 provider 状态。索引不存在、部分摄取、源文件删除和检索失败应各自可诊断，不能统称「没有历史」。关闭时仍执行阶段 A，安装或检测到 provider 不应自动启用，也不应扫描未授权历史。
阶段 C：有证据表明需要长期经验后，再复用 OpenViking 接入。 将已验证的结果沉淀为有来源、版本和适用范围的经验，支持 supersede/retract；即时接续不等待异步提取。可以与 Hindsight/Mem0 做小范围对照，但一次选择一个后端，不先做通用全家桶。
阶段 D：多主机与协调单独验收。 明确实际的数据传输/共享后端、来源命名空间、代码与产物到达目标主机的机制，以及现有 authority 的原子接管与冲突恢复。不要将复制数据库或记忆可见性描述成完整 session 迁移。将这部分留到后续，并不削弱目标，而是让每个阶段都能独立证明自己。
6. 验收应证明「更可靠地继续完成工作」
建议准备一小组可复现、合成或经授权脱敏的接续任务，比较当前状态 + handoff 基线与单个 provider 增强；固定时间截点、模型和预算。记录下一步是否有可回读证据、重复探索量、过期状态误采纳率、恢复后完成率/重复副作用，以及耗时、token、存储和维护成本。不要只测搜索命中率或摘要看起来是否合理。本评论没有启动 benchmark 或索引真实用户历史。
边界用例至少包括：同名跨主机 session、压缩/分叉后被替代的证据、来源撤回、部分索引、无权限 viewer、检索内容夹带指令、Todo 已完成/claim 冲突、记录提交后接管前崩溃、重放与并发写入。provider 关闭/不可用时须保持基线流程；敏感内容不能因
public_safe自声明或缺省 viewer 穿过访问范围。我支持继续推进这个方向，也建议不要把精力花在逐轮扩大自建 substrate 来填补评审问题上。下一版最有说服力的成果，是一次带来源、可重放、有权限校验、失败可恢复的真实接续，以及清楚的 build-vs-reuse 决策。 这比同时承诺完整 memory/coordination 平台更能让这项工作扎实落地。#4094 的具体实现缺陷和本轮已修复项会在 PR 评审中单独列明。
xiaods commentedon Sep 9, 2026
@huangruiteng 感谢评审，跨会话接续这个方向正好是我工作中需要的，所以我会小步迭代，慢慢前进。
xiaods commentedon Sep 11, 2026
xiaods commentedon Sep 11, 2026
[-][Feature]: Cross-session memory substrate for agent-session context transfer[/-][+][Feature]: A bounded, explicit handoff workflow over the canonical Todo authority.[/+][-][Feature]: A bounded, explicit handoff workflow over the canonical Todo authority.[/-][+][Feature]: explicit revision-guarded cross-agent session continuation[/+]