Skip to content

feat(memory): add semantic self-evolving memory review for Classic and Native #322

Open
Open
feat(memory): add semantic self-evolving memory review for Classic and Native#322
Assignees
benym
Labels
enhancementNew feature or requestneeds-triage

Description

@benym
benym
opened on Aug 16, 2026

🔎 Existing issue check

当前没有 Issue 完整负责：让 Classic 与 Native 共用一个固定的语义记忆评审 Skill，并由 Runtime 以可验证、可迁移、可评估的方式完成自进化记忆。

🧭 Problem

Comet 已有 Personal Memory 插件、CLI、Markdown/Git 存储、候选证据和检索能力，但当前自动学习仍主要把工作流命令摘要当成记忆候选，离 Hermes 类“对一次工作做语义复盘，只保留以后真正有用的信息”还有明显差距。

当前代码中的关键问题：

  1. domains/comet-entry/plugin-context.ts 的 recordCometWorkflowResult 使用固定 category=workflow-operation，并把 summary 或 workflow + command 作为 text；这记录的是“做过什么命令”，不是“以后应该记住什么”。
  2. domains/comet-plugin/integration.ts 把同一生命周期事件同时投递给 user 与 project scope，无法让每一条记忆只选择一个准确范围。
  3. candidateKey 虽然由入口产生，但在 domains/comet-memory/plugin.ts 转换为 MemoryObservation 时丢失。
  4. MemoryObservation 没有 language、candidateKey、action 或目标记忆字段；Runtime 无法可靠表达 create / update / forget / skip。
  5. observation key 当前主要由 projectKey + changeId 组成；同一个 change 内的多个不同候选可能互相去重，而同一语义跨 change 的合并又不够明确。
  6. Native、Classic、hotfix、tweak Skill 中存在分散且模糊的 comet memory observe 指令，没有一个共享的记忆质量协议。
  7. .comet/config.yaml 已可配置 Native/Classic language，但自动记忆正文和用户可见标签没有把该语言作为强契约。配置为 zh-CN 时，用户仍可能看到难懂的英文或命令摘要。
  8. 现有测试证明状态机和集成能运行，但没有衡量“该不该记、记得是否准确、是否更新旧记忆、是否真的改善后续任务”。

结果是：记忆数量可以增长，但有效性、可读性和行为收益没有被证明。

🎯 Goal

为 Comet 增加一套同时服务 Classic 与 Native 的“自进化记忆”闭环：

  • 新增一个独立、固定、共享的 comet-memory Skill，负责语义判断；
  • Skill 自身不自进化，不修改任何 Skill、AGENTS.md、项目规则或工作流契约；
  • Runtime 负责触发时机、输入边界、语言、scope、证据、去重、安全、持久化和失败降级；
  • Personal Memory 插件继续负责状态、用户可读 Markdown、Git 同步、检索、纠正、删除和 Dashboard 数据；
  • 显式“请记住”立即处理；隐式偏好只在重复且一致的成功证据后激活；
  • 在稳定检查点复盘，不在每轮对话后记录；
  • 配置语言为 zh-CN 时，自动生成的用户可读记忆正文、标题和说明必须是中文；
  • 用专门 Eval 证明语义评审比当前 command-summary observe 更准、更少噪音，并能改善后续任务。

这不是 Skill 自进化，也不是把项目规则学习重新包装成个人记忆。

🧩 Scope boundaries

组件 负责 不负责
comet-memory Skill 从受限证据中识别可复用记忆，输出 create / update / forget / skip 自己修改自己、写文件、决定触发、绕过 Runtime
Runtime / host bridge 构造评审包、选择语言与 workflow、触发 Skill、校验动作、控制 scope/证据/安全/超时 用硬编码命令摘要替代语义评审
Personal Memory domain/plugin 候选、激活、合并、历史、持久化、同步、检索、删除、恢复 修改 Skill、AGENTS.md 或 Project Rules
Classic / Native Skill 在统一稳定检查点调用共享能力 各自复制一套记忆判断规则
Project Rules 项目级正式规则的提议与采纳 接收个人偏好或被 comet-memory 自动修改
Dashboard / CLI 展示、检索、暂停、纠正、忘记、同步 重新实现记忆状态推导

🏗️ Proposed architecture

Classic / Native stable checkpoint
        │
        ▼
Runtime builds bounded MemoryReviewPacket
        │
        ▼
fixed shared comet-memory Skill
        │
        ▼
create | update | forget | skip
        │
        ▼
Runtime validates language, scope, evidence, target and safety
        │
        ▼
Personal Memory plugin persists readable Markdown + machine state
        │
        ▼
bounded profile / task-time retrieval / Dashboard / Git sync

1. 独立固定的 comet-memory Skill

新增双语内置 Skill：

  • assets/skills-zh/comet-memory/SKILL.md
  • assets/skills/comet-memory/SKILL.md

中文语义先实现并确认，再同步英文；两版必须保持行为契约一致。

Skill 只做一件事：从 Runtime 提供的有界评审包中判断是否存在长期有用的信息，并返回结构化动作。它不得：

  • 修改自身或其他 Skill；
  • 修改 AGENTS.md、CLAUDE.md、Project Rules、Specs 或用户代码；
  • 主动扫描完整仓库、完整 transcript、Git diff 或日志；
  • 自行选择存储目录或直接写记忆文件；
  • 把“一次命令成功”“完成了某个 change”本身当成记忆；
  • 在无证据时猜测用户偏好。

2. 结构化评审契约

在 comet-memory domain 中定义版本化契约；CLI/Runtime 和 Skill 共享同一 schema，不从自然语言输出中猜字段。

interface MemoryReviewPacketV1 {
  schema: "comet.memory.review.v1";
  language: "en" | "zh-CN";
  workflow: "classic" | "native";
  changeId: string;
  checkpoint: string;
  projectKey: string;
  explicitRequests: readonly EvidenceItem[];
  userCorrections: readonly EvidenceItem[];
  verifiedOutcomes: readonly EvidenceItem[];
  relatedMemories: readonly ExistingMemory[];
  limits: {
    maxActions: number;
    maxEvidenceItems: number;
    maxBytes: number;
  };
}

type MemoryReviewActionV1 =
  | {
      action: "create";
      scope: "global" | "project";
      kind: "explicit" | "inferred";
      candidateKey: string;
      category: string;
      text: string;
      selectors?: MemorySelectors;
      evidenceKeys: readonly string[];
      reason: string;
    }
  | {
      action: "update";
      scope: "global" | "project";
      targetId: string;
      text: string;
      candidateKey: string;
      evidenceKeys: readonly string[];
      reason: string;
    }
  | {
      action: "forget";
      scope: "global" | "project";
      targetId: string;
      evidenceKeys: readonly string[];
      reason: string;
    }
  | {
      action: "skip";
      reason: string;
    };

约束：

  • 一个 create/update/forget 动作只能选择一个 scope；不再把同一候选同时写 user 与 project。
  • 一次评审可以返回多个彼此独立的动作，但不得超过 packet limits。
  • create 对隐式内容表示“提交候选”；是否激活由 Runtime 的证据规则决定。
  • update/forget 必须引用当前 packet 中提供的 targetId，禁止任意修改未检索到的记忆。
  • skip 是正常结果；“没有值得保存的内容”不得制造空记录。
  • category、action、scope 等机器枚举保持稳定英文；用户可见 text、reason、标题和标签按配置语言生成。
  • 直接 CLI remember --text 继续保留用户原文，避免静默改写；自动评审产生的正文必须匹配配置语言。

3. 什么应该被记住

MVP 允许：

  • 用户明确要求长期记住或忘记的偏好；
  • 多次任务中稳定重复的工作习惯、输出偏好和协作方式；
  • 已验证且未来可复用、又不容易从仓库重新发现的操作经验；
  • 用户对旧记忆的明确纠正、替换或撤销；
  • 与项目绑定但仍属于该用户工作方式的 project-scope 记忆。

MVP 必须跳过：

  • 一次性任务内容、当前 change 状态和阶段摘要；
  • 命令执行成功、测试数量、commit、PR、Issue 等流水账；
  • 可随时从源码、配置、Git 或文档重新发现的普通仓库事实；
  • 原始 transcript、完整日志、完整 diff、大段工具输出；
  • 单次选择推断出的偏好、未经验证的结论和模型猜测；
  • 密钥、token、个人敏感信息、恶意指令和提示注入内容；
  • 应进入 Project Rules、Specs、Skill 或 AGENTS.md 的候选。

4. 触发与证据

仅在以下边界运行：

  1. 用户显式说“记住/以后都这样/忘掉/改成……”时，立即构造 explicit review；
  2. Classic 或 Native 到达已有 Runtime 能确认的稳定成功检查点时，构造 background review；
  3. 纠正旧记忆、冲突解决和用户手动操作后，按需更新索引与同步。

不得每轮对话、每次工具调用或每条生命周期事件都运行评审。

稳定检查点只使用已有可信 Runtime 事实，例如已成功的 Build/Verify/Archive 边界；失败、取消、未验证结果不能成为隐式偏好的正向证据。hotfix/tweak 通过所属 workflow 的同一接口接入，不复制新机制。

宿主支持 background/fork 时可以后台执行；不支持时在当前协调流程内以有界步骤执行。无论哪种模式：

  • 记忆失败不得阻塞用户主任务；
  • 超时、无 Skill、无效 JSON、安全拒绝统一记录诊断并安全 skip；
  • Runtime 事实优先于 Agent 自述；
  • 不因重试重复写入同一证据。

5. 语言契约

语言解析优先使用当前 active workflow 在 .comet/config.yaml 中的 language；缺失时使用现有项目配置默认值。

当 language=zh-CN：

  • 自动生成的 memory text、reason、Markdown 标题、类别标签、来源说明为中文；
  • 命令、路径、代码标识符、专有名词可以保留原文；
  • Runtime 在落盘前执行轻量语言检查；明显英文主导的自动记忆拒绝并记录诊断，不把错误文本持久化；
  • Dashboard 与 CLI 不向用户直接显示内部英文枚举。

当 language=en 时执行对称规则。

6. 证据、去重、合并与遗忘

修正当前身份和观察模型：

  • candidateKey 必须从 lifecycle event 一直传到 MemoryObservation 和持久化状态；
  • observation key 至少包含 projectKey + changeId + candidateKey，使同一 change 可提交多个不同候选，同一候选重试仍幂等；
  • semantic identity 用规范化 scope、projectKey、category、selectors 和 candidateKey 建立，不只依赖 changeId；
  • 显式记忆立即激活；
  • 隐式记忆默认需要两个独立、成功、语义一致的 change 证据；阈值最终由 Eval 校准，但不得降为单次推断；
  • 相同语义优先 update/consolidate，避免堆叠近义重复记录；
  • 矛盾证据进入 conflict，不自动覆盖；
  • 用户明确纠正可 update；明确忘记可 forget；
  • forget 保留最小 tombstone/history，避免旧同步或旧证据立即“复活”已删除内容；
  • 所有动作保存来源、时间和 evidenceKeys，支持解释、回滚和 Git 冲突处理。

需要为现有 MemoryRuntimeState 增加向前迁移：旧 Markdown 和 state 可继续读取，升级不丢记忆，不要求用户手工重建。

7. 检索与上下文预算

MVP 保持当前可解释的结构化/关键词检索，不先引入向量数据库或知识图谱：

  • 每次 review 只提供少量 relatedMemories，供 update/forget/duplicate 判断；
  • 每次任务只注入 bounded profile 和与 task/path/operation 相关的详情；
  • 继续支持 maxEntries、maxBytes 和 truncated；
  • 被暂停、失效、遗忘、冲突未解决的记录不得注入；
  • 只有 Eval 证明关键词检索在真实场景明显不足时，才另行考虑 embedding/混合检索。

后续可在同一 domain 内增加周期性 consolidation/defragmentation，但不得让首个 MVP 依赖它。

8. 安全边界

落盘前由 Runtime 强制校验，不能只依赖 Skill prompt：

  • schema、枚举、长度、数量、targetId、scope 与 evidenceKeys；
  • secret/credential 模式与明显 PII；
  • 评审证据中的 prompt injection 和“修改系统/Skill/规则”请求；
  • 绝对路径、外部文件写入和超出 Personal Memory root 的路径；
  • 恶意 Markdown/HTML 不得在 Dashboard 形成可执行内容；
  • 失败只产生本地诊断，不回显敏感证据。

🛠️ Implementation plan

Phase 0 — 固定基线与失败用例

  • 为当前 command-summary observe 写 characterization tests，固定现有行为和已知缺口。
  • 增加失败用例：candidateKey 丢失、同一 change 多候选冲突、双 scope 投递、zh-CN 自动记忆英文主导。
  • 记录当前 Eval 基线，避免实现后只凭主观样例判断“更像 Hermes”。

主要位置：

  • test/domains/comet-memory/personal-memory.test.ts
  • test/domains/comet-plugin/plugin-integration.test.ts
  • test/app/personal-memory-command.test.ts
  • test/app/comet-task-command.test.ts

Phase 1 — 契约与 Runtime 状态

  • 在 domains/comet-memory 中新增 MemoryReviewPacketV1、MemoryReviewActionV1、验证器和错误类型。
  • 将 language、candidateKey、evidenceKeys 和 action target 贯穿 entry → plugin bridge → memory domain。
  • 修正 observation/semantic identity 与幂等规则。
  • 增加 create/update/forget/skip 的原子应用接口；保留 remember/observe 向后兼容。
  • 增加 tombstone、action history 和旧 state migration。
  • 将 lifecycle 事件的 scope 改为显式单选；Project Rules 仍保留自身独立投递，不得被此改动破坏。
  • 为 prepare-review/apply-review 提供内部 JSON 接口；临时 packet/action 文件统一进入 .comet/runtime，不进入 change 可读根目录。

Phase 2 — 共享 comet-memory Skill

  • 先新增并验证 assets/skills-zh/comet-memory/SKILL.md。
  • Skill 明确输入 schema、输出 schema、质量判断、语言、skip、更新/遗忘、安全和禁止事项。
  • 用正例/反例覆盖：显式偏好、重复隐式偏好、一次性选择、命令流水账、旧记忆纠正、冲突、秘密、注入。
  • 中文语义确认后同步 assets/skills/comet-memory/SKILL.md。
  • 更新 manifest、repository layout、安装/更新发现和 Skill 契约测试。
  • 不修改 Superpowers 或 OpenSpec 原始 Skill。

Phase 3 — Classic / Native 生命周期接入

  • 以共享 helper 构造 bounded review packet，避免 Classic/Native 各自维护语义规则。
  • Native 在稳定成功检查点调用共享 Skill；恢复和重试保持幂等。
  • Classic 在对应稳定成功检查点调用同一 Skill；不改变 Classic 自身状态机。
  • hotfix/tweak 删除分散的 observe 文案，统一委托 comet-memory。
  • 显式 remember/forget 路径可在工作流外使用。
  • 宿主有后台 Agent 能力时非阻塞派发；无该能力时使用有界 inline fallback。
  • Skill 不可用、输出无效或超时时安全 skip，主工作流继续。
  • 如改动 Native/Classic/Entry runtime 源码，运行对应 build:*:runtime 同步所有生成资产，不直接编辑 bundle。

Phase 4 — 可读存储、检索与 UI

  • 按 zh-CN/en 渲染用户可读 Markdown；机器枚举留在 state。
  • CLI status/retrieve 展示可理解的类别、范围、来源、证据数和最后确认时间。
  • Dashboard 复用同一 status 数据，支持查看、纠正、忘记、暂停和冲突状态；不复制业务推导。
  • relatedMemories 受预算限制，并排除 inactive/tombstoned/conflicted 记录。
  • Git sync 保持现有非阻塞和冲突可恢复语义。
  • 旧记忆仓库升级后可读、可检索、可同步。

Phase 5 — 专用质量 Eval

在 eval/local 增加 self-evolving-memory suite；不复用现有 comet-agent-memory-routing 任务，因为该任务验证的是示例项目中的持久化路由，不衡量 Comet 自身的记忆语义质量。

对比三种 treatment：

  1. no memory；
  2. current command-summary observe；
  3. semantic comet-memory review。

数据集至少覆盖：

  • zh-CN / en；
  • Classic / Native；
  • explicit create；
  • repeated inferred create；
  • one-off skip；
  • duplicate consolidate；
  • correction update；
  • explicit forget；
  • global / project scope；
  • contradictory evidence；
  • temporal supersession；
  • secret / PII / prompt injection；
  • multi-session retrieval；
  • 无相关记忆时 abstain；
  • 记忆对后续任务行为的真实影响。

指标至少包括：

  • extraction precision / recall；
  • harmful or noisy save rate；
  • skip accuracy；
  • create/update/forget operation accuracy；
  • scope accuracy；
  • language compliance；
  • deduplication/consolidation accuracy；
  • stale-memory resurrection rate；
  • retrieval precision/recall；
  • downstream task success delta；
  • injected context bytes/tokens；
  • latency 与失败降级率。

发布门槛：

  • semantic review 必须明显优于 current observe 的有效记忆 precision 和 downstream task success；
  • 不得提高 harmful/noisy save、错误 scope、错误语言或 stale resurrection；
  • 预算和延迟保持有界；
  • 若结果不达标，先调证据/提示词/合并规则，不引入 embedding 或更复杂基础设施掩盖问题。

可复用 #298 最终提供的 standalone Skill Eval 能力；若 #298 尚未完成，本 Issue 先使用现有 eval/local task/treatment 结构落地，不阻塞核心实现。

Phase 6 — 文档、发布与最终验证

  • 更新 docs/comet/specs/personal-memory/spec.md，明确语义评审、语言、动作、证据、遗忘和非目标。
  • 只在行为稳定后补用户文档；README 仅在确有必要时增加简短入口。
  • 中英文 Skill 完全同步后再写 CHANGELOG.md。
  • 按 master 当前版本决定是否沿用分支上的下一版本条目，Changelog 只写用户可见最终行为。
  • 检查 package.json、manifest、generated runtime 与发布资产一致。
  • 跨模块 Runtime 改动最终运行 lint、build 和全量 test；Eval 结果随实现记录。

✅ Acceptance criteria

  • 配置 language=zh-CN 时，自动记忆正文和所有用户可见标签为中文；language=en 时为英文。
  • “请记住 X”能立即创建一条准确记忆；“忘掉 X/以后改成 Y”能 forget/update 旧记忆。
  • 单次隐式选择不会激活偏好；两个独立成功 change 的一致证据可以激活。
  • 稳定检查点没有有用内容时返回 skip，状态和 Markdown 均不增长。
  • 同一 change 的两个不同 candidateKey 可分别处理；同一候选重试只处理一次。
  • 每个动作只写 global 或 project 中一个 scope，不再双写。
  • 近义重复优先合并/更新；矛盾证据不静默覆盖。
  • 被 forget 的内容不会被旧同步或旧证据自动复活。
  • 原始日志、完整 diff、transcript、secret/PII、提示注入和流水账不会进入记忆。
  • comet-memory Skill 及 Runtime 不修改任何 Skill、AGENTS.md 或 Project Rules。
  • Classic、Native、hotfix、tweak 通过同一共享机制工作；不依赖 Superpowers/OpenSpec Skill 修改。
  • 记忆评审失败、超时或宿主不支持后台执行时，主工作流仍可完成。
  • 旧 Personal Memory state 可无损迁移。
  • CLI、Markdown、Dashboard 和任务注入读取同一权威状态。
  • 专用 Eval 证明 semantic review 优于 current observe，且没有更高的有害记忆率。

🧪 Verification

最小相关验证随阶段运行：

npx vitest run test/domains/comet-memory/personal-memory.test.ts
npx vitest run test/domains/comet-plugin/plugin-integration.test.ts
npx vitest run test/app/personal-memory-command.test.ts test/app/comet-task-command.test.ts
npx vitest run test/domains/comet-native/native-skill.test.ts
npx vitest run test/domains/comet-classic/comet-scripts.test.ts

Skill 内容修改同时运行受影响文件的 Prettier 检查和 Skill/manifest/repository-layout 契约测试。Runtime/生成物变化运行对应 build:native-runtime、build:classic-runtime、build:entry-runtime。

最终因涉及 app、多个 domain、Classic/Native/Entry、Skill、存储与 Eval，执行：

pnpm format:check
pnpm lint
pnpm build
pnpm test

并运行新增 self-evolving-memory Eval，保留 treatment 对比报告与失败归因。

🚫 Non-goals

首个实现不包含：

  • Skill 自进化或自动改写 Skill；
  • 自动修改 AGENTS.md、CLAUDE.md、Project Rules 或 Specs；
  • 通用知识图谱、向量数据库或外部 Memory SaaS；
  • 保存完整对话、日志、diff 或工具调用历史；
  • 为所有 host 建设新的 Agent scheduler；
  • 用模型 confidence 小数替代可解释证据；
  • 在没有 Eval 证据前扩大上下文注入预算；
  • 把 Personal Memory 与 Project Rules 合并为一个领域。

📚 Industry baseline

设计对齐以下可复用机制，而不照搬具体供应商实现：

📎 Local design note

完整业界调研和差距分析已整理在：

  • docs/research/2026-08-16-hermes-self-improving-memory-comparison.md

该研究文档当前仅作为实现输入；本 Issue 是后续实施、验收和发布的权威任务清单。

Metadata

Metadata

Assignees

Labels

enhancementNew feature or requestneeds-triage

Type

No type

Projects

comet roadmap
Status
In progress

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions