# deskpaw-memory

DeskPaw 的本地记忆与上下文整理模块。它作为 `deskpaw-agent` 的平级服务运行，通过本地 socket 提供：

- 任务卡和执行结果的持久化；
- 新旧任务关联度提示；
- 日程附属资料夹；
- 每轮执行前的有限上下文包；
- 按 03:30 工作日组织的话题经历、长期事实和技能草稿；
- 主动整理记录与可观测事件。

模块不保存隐藏思考，不接管日程执行，不直接操作电脑或发送消息。Agent 不依赖本服务才能运行；服务离线时自动降级。

`deploy/deskpaw-memory.service` 是当前 KickPi 部署模板。`bin/run-memory` 会读取设备配置中的 `DESKPAW_NODE_BIN`，避免 systemd 找不到 NVM 安装的 Node。服务应先于 Agent 启动；它故障重启时不会要求 Agent 一起重启。

## 启动

Linux 默认 socket 为 `~/.deskpaw/runtime/memory.sock`：

```bash
npm start
```

正式状态统一保存在 `~/.deskpaw/memory/`：SQLite 数据库位于
`data/memory.sqlite3`，日程和项目资料位于 `bundles/`。旧版 Python
记忆服务的数据应迁到 `~/.deskpaw/memory-legacy/`，不要与本模块共用数据库。

可配置：

```text
DESKPAW_STATE_DIR=/path/to/state
DESKPAW_MEMORY_SOCKET=/path/to/memory.sock
DESKPAW_MEMORY_DB=/path/to/memory.sqlite
DESKPAW_MEMORY_BUNDLES=/path/to/bundles
```

协议为单请求连接的 JSON Lines。请求包含 `id、method、params`，响应包含 `id、ok、result/error`。

接口：`health`、`memory.recall`、`interaction.remember`、`transition.assess`、`context.prepare`、`task.complete`、`task.list`、`consolidation.record`、`memory.maintenance.status/plan/commit`、`memory.topic.get`、`memory.skill.list/get/set_status`、`bundle.get/list/document.put`。修改资料使用 `expected_revision`，防止猫窝和桌喵同时编辑时旧内容覆盖新内容。

## 顶层记忆

DeskPaw 使用一个 Session。顶层 Agent 每轮先同步已完成的问答，再调用 `memory.recall`；
Memory 返回相关与最近的问答、任务卡以及资料包，供顶层优先回答“之前的任务”“刚才怎么样”等问题。
来源仅作为 `source` 元数据保存，不作为检索过滤条件。同步按 `interaction_id` 幂等写入，
并经 `safeMemoryText` 过滤敏感文本；不要在记忆资料中放入凭据或隐藏推理。

`memory.recall` 请求示例：

```json
{"id":"request-1","method":"memory.recall","params":{"query":"之前 UFO 检查怎么样了","limit":8}}
```

结果保留旧的任务卡、问答和资料包字段，并新增 `recent_workdays`、`related_topics`、
`core_facts`、`related_facts` 和 `relevant_skills`。话题按标题和概括召回，长期事实按范围和内容匹配；
上层会裁剪候选数量，详细经历通过 `memory.topic.get` 按话题 ID 分页读取。
旧任务卡检索仍只扫描最近 100 张、逐条问答检索仍只扫描最近 200 条；
话题检索目前扫描全部话题并排序，尚未建立全文索引；数据量显著增长后应换成索引召回。
`transition.assess` 只提示任务切换，
不决定经历是否合并。

## 话题与整理

记忆中的 `topic_id` 是话题单元，既可表示执行任务，也可表示闲聊和讨论；它与 Agent 执行队列的
`task_id` 不同。一个话题可跨工作日继续。工作日固定为北京时间 03:30 至次日 03:29:59，
与实际压缩作业是否延期无关。SQLite 中的 `topic_interactions` 只建立关联，不改写原始交互；
`topic_segments` 保存每日极简概括。最近三个有话题片段的工作日进入顶层概览，旧话题仍可检索。
原始执行日志仍由 Agent 运行时 SQLite 保存；Agent 按话题读取详情时，利用关联的执行任务 ID
补充有限的执行日志，不在 Memory 中复制无界工具输出。

下层 Agent 在无执行任务时分批调用 `memory.maintenance.plan`，使用执行模型归类话题、概括结果与问题，
然后用 `memory.maintenance.commit` 原子写入。每条交互必须恰好分配一次；重启中断不会删除原始记录。
一小时无用户或执行活动后会整理未归档交互；跨过 03:30 时，在下层空闲后复核前一工作日。
整理期间上层 Supervisor 仍可交流，新执行任务排队等待。Memory 服务本身不调用模型或 Executor。

长期事实必须附可逐字核对的证据，但不要求每批对话都提炼事实。`profile` 只收来自用户原话的
稳定身份、交流偏好和职业工作方式，并须标明 `profile_kind`；当前推进的工作用 `project`，
只按相关性提供，不常驻顶层画像。具体日程、临时位置、输入法状态、软件是否已打开和单次测试结果
留在话题经历，不提炼为稳定画像。`environment` 仅限受控设备范围；无论观察来自用户原话还是
任务结果，单个工作日都只能是 `candidate`，跨两个有效工作日有独立证据才会变成 `active`。
仅有上层回复复述不算验证；三天未获佐证的候选在日审中停用。已停用的事实不会被整理作业自动重启。
少量全局 `profile` 常驻上层，`project` 和已确认的设备事实按问题相关性挑选。
用户指导产生的技能只进入 `draft`，须用户本轮明确要求启用后才能
`set_status` 为 `active`；执行层可以读取草稿用于审阅，但只有已启用技能可作为执行参考。
不要把凭据、隐藏思考或无界工具输出写入记忆。

服务故障不会暂停执行队列。顶层会显示实际的记忆请求错误；恢复服务后，
后续交互会继续同步最近的已完成问答。

## 资料夹

日程第一次运行时会按稳定 `schedule_id` 建立：

```text
bundles/schedule/<schedule_id>/
  INDEX.md
  requirements.md
  preferences.md
  lessons.md
  state.json
  runs/<run_id>/summary.md
```

数据库保存权威状态，以上文件用于猫窝展示和按需阅读。