deskpaw-memory/README.md

deskpaw-memory

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

• 任务卡和执行结果的持久化；
• 新旧任务关联度提示；
• 日程附属资料夹；
• 每轮执行前的有限上下文包；
• 主动整理记录与可观测事件。

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

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

启动

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

npm start

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

可配置：

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、bundle.get、bundle.list、bundle.document.put。修改资料使用 expected_revision，防止猫窝和桌喵同时编辑时旧内容覆盖新内容。

顶层记忆

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

memory.recall 请求示例：

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

结果包含 related_task_cards、recent_task_cards、related_interactions、 recent_interactions 和 bundles。每类结果有界：最多返回 limit 条任务或问答、 最多 3 个资料包。当前相关性计算扫描最近 100 张任务卡和 200 条顶层问答； 更早内容仍保存在 SQLite，但不会进入这一版召回结果。transition.assess 只判断任务切换及上下文整理， 不替代记忆召回。

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

资料夹

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

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

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