HaroCue 如何工作

HaroCue 在「你正在使用的应用」和「需要上下文的功能」之间工作。你不必上传整段屏幕或重放全部记录：先选择允许的线索，保存可核对的依据，再在当前工作区内取回有资格的记忆。

心智模型

没有记忆层	使用 HaroCue
每次需要时重新翻找窗口和聊天记录	把值得复用的线索整理成带来源的记忆
让模型反复阅读大段旧文本	只把当前问题需要的记忆交给 Cue 或问答
换一个工作区就丢掉上下文，或把不同项目混在一起	用工作区、时间和版本限制每次读取
不知道一句建议从哪里来	在记忆、回答和回顾旁边查看原始依据

线索与记忆

你在桌面上留下的是线索，内核保存的是可以再次核对的记忆。公开样例可以这样理解：

输入线索	可复用记忆	依据
工作笔记：白鹭计划的体验测试安排在周五	白鹭计划的体验测试安排在周五	EvidenceBlock 中的原文片段
邮件草稿：发布前需要核对隐私说明	白鹭计划发布前需要核对隐私说明	来源类型、观察时间和引用范围
你在记忆页写下「以后先看隐私说明」	用户确认的偏好或决定	UserInput Evidence + User Claim

边界 记忆是从允许的文字中提取的候选，不是屏幕全文的复制品。没有可读来源、权限不足或采样不稳定时，结果可以为空。

两个阶段：写入与读取

大多数功能都可以归纳为两个阶段：先把值得保留的内容写成记忆，再在下一次 Cue、问答或回顾前读取相关内容。

1. 写入记忆

触发条件

• 记录已开启，且你同意了对应的桌面权限
• 当前前台窗口和工作区稳定，并且属于允许采样的范围
• 或者你在记忆页明确写下一条内容

处理步骤

1. 捕捉线索：macOS 优先读取 AX 可访问文字；需要补充时，才在本机读取单帧 OCR。
2. 保存依据：适配器提交 EvidenceInput，内核保存不可变的 EvidenceBlock，记录来源、时间和保留期。
3. 提出候选：抽取任务只向模型发放受限的 source grants；模型返回 Claim 文本、类型、有效时间和范围句柄。
4. 核对并提交：内核重新解析 UTF-8 范围，检查来源、作用域、时间、revision 和 scope_epoch，通过后才原子写入 Claim。

写入结果

• 自动抽取的记忆保留 Producer 身份，表示它来自模型提案。
• 手动记录写入 UserInput Evidence 和 User Claim，表示它来自你的明确输入。
• 模型的自信度不会自动变成用户确认；纠正和确认是独立的用户动作。

对应代码：crates/harocue-runtime/src/orchestrator.rs、crates/harocue-adapters/src/context_ax.rs、crates/harocue-adapters/src/screen_ocr_macos.rs、crates/harocue-memory/src/extraction.rs、crates/harocue-memory/src/model.rs。

2. 读取记忆

触发条件

• 停顿后需要一条 Cue 建议
• 你在问题末尾输入 /，主动发起原位问答
• 你打开记忆页、恢复上下文，或按日、周、月生成回顾草稿

处理步骤

1. 确定范围：查询带着当前工作区、scope_epoch、known_at 和 valid_at；没有明确作用域时不会扩大搜索。
2. 通过资格门：排除被纠正、冲突、失效、遗忘或失去来源支持的 Claim。Cue 只接受 Current + Grounded。
3. 合并候选：在资格门之后合并词法、实体和版本一致的可选语义候选。
4. 装入预算：按 max_items 和 max_bytes 生成有界的 MemoryPack，完整条目不会被截断。
5. 展示前复核：显示和 Tab 接受前重新比较作用域、版本、来源和大小；旧快照不能跨工作区或删除动作继续显示。

读取结果

• Cue 把建议和引用来源放回原输入处，按 Tab 接受，或按 Esc 收起。
• / 问答把答案、查询过程和来源一起返回，不会把自动建议伪装成用户主动提问。
• 回顾先生成带来源的待审草稿，只有你请求「生成文字版」时才调用模型。

对应代码：crates/harocue-memory/src/retrieval.rs、crates/harocue-memory/src/indexed.rs、crates/harocue-memory/src/semantic.rs、crates/harocue-runtime/src/product_memory.rs、crates/harocue-runtime/src/completion_engine.rs。

检索信号

查询不是一次模糊相似度搜索，而是先确定哪些记忆有资格，再组合多个信号排列结果。

信号	做什么	适合回答
作用域	限制在当前工作区或明确授权的全局偏好	避免不同项目互相混入
状态与来源	排除失效、冲突、遗忘或没有可读依据的 Claim	当前能否可靠使用
词法	用 BM25 风格统计和中文相邻双字词匹配原词	名称、编号和事实查找
实体	使用真实的人物、项目和来源连接增强候选	关于某个人或项目的问题
语义	接收作用域和版本一致的可选语义候选	概念相近但用词不同的问题
时间	根据 known_at、valid_at 和 Transitions 判断生效与过期	「什么时候」「现在是否仍然」

ReadIndex、语义索引和图谱关系都是可重建的候选投影。它们不能绕过作用域、时间、来源或遗忘检查；Grounded 只表示引用片段仍可读取，不表示模型推断已经被语义证明。

记忆在哪里

资产	保存什么	用途
EvidenceBlock	不可变的来源文字、来源 ID、观察时间和保留期	展开「为什么记得」并重新核对
Claim	事实、偏好、决定或承诺，以及状态、关系和引用	作为可复用的记忆候选
ReadIndex / 语义索引	词法、实体或向量候选	加速查询，随内核状态重建
MemoryPack	某个 revision 和作用域上的有界结果快照	交给 Cue、问答或回顾，展示前必须复核

Claim 与 Evidence 是当前记忆的依据；索引、图谱和回顾是可以重新生成的读取视图。

用户可以改变什么

记忆不会被后台整理器静默覆盖。你查看来源后，可以选择适合的控制动作：

动作	结果	什么时候用
纠正	写入新的 User Claim，并保留 Corrects 关系	原来的表述或事实不对
停止使用	记录带生效时间的 Transitions	以前成立，后来不再适用
局部例外	在明确工作区内建立规则	某个项目需要不同处理方式
遗忘	清除 Claim 或 Evidence，并阻止普通读取	不希望它继续被使用
清空作用域	清除选定范围并推进 scope_epoch	需要重新开始一个工作区

每个动作都带 expected_revision 和 scope_epoch 做原子校验。删除、纠正或切换工作区后，旧的 Cue、回顾草稿和后台任务必须重新验证。

先记住这四点

• 先有允许的来源，再有可以复用的记忆。
• 先过资格门，再按相关性排序；索引不能替代资格判断。
• Producer 表示模型提出，User 表示你明确输入或确认。
• 公开演示使用固定样例，不读取你的电脑，也不连接实时模型。

下一步

• 记忆类型：Claim、来源、状态和作用域。
• 添加记忆：自动抽取与手动记录。
• 搜索记忆：资格门、排序和结果预算。
• 更新记忆：纠正、停止使用和局部例外。
• 删除记忆：遗忘 Claim、Evidence 和作用域。
• 记忆评估：写入、检索、展示和生命周期验证。

代码地图

关注点	代码证据
采样、前台绑定、拒绝采样	crates/harocue-runtime/src/orchestrator.rs、crates/harocue-adapters/src/window_unified.rs
Evidence、Claim、关系与版本	crates/harocue-memory/src/model.rs、crates/harocue-memory/src/mutation.rs
抽取与引用范围	crates/harocue-memory/src/extraction.rs
过滤、排序、字节预算	crates/harocue-memory/src/retrieval.rs、crates/harocue-memory/src/indexed.rs
工作区、Cue 与回顾适配	crates/harocue-runtime/src/product_memory.rs、crates/harocue-runtime/src/completion_engine.rs
图谱与来源查看	frontend/src/knowledge-map.ts、crates/harocue-runtime/src/knowledge_map.rs