05 — 跨会话用户记忆：三种注入模式

跨会话用户记忆：三种注入模式

学习目标

理解 CodeWhale 的用户记忆系统：三种记忆添加模式、注入位置、隐私边界与项目指令的边界划分。

前置知识

• 记忆系统设计 — 短期/长期记忆分层与文件系统存储方案

下文假设你已理解上述概念，直接聚焦 CodeWhale 的具体实现。

项目实践

配置与启用

记忆默认关闭（零开销）。启用方式二选一：

# 环境变量
export DEEPSEEK_MEMORY=on

# 配置文件 ~/.codewhale/config.toml
[memory]
enabled = true

接受的真值：1, on, true, yes, y, enabled。

三种添加模式

模式 1：# 前缀

在 composer 中输入以 # 开头（但不是 ## 或 #!）的单行文本：

# 这个仓库偏好使用 4 空格缩进

TUI 拦截输入并追加时间戳 bullet 到记忆文件。不触发 turn——输入被消费，状态栏确认写入路径。

多个 #（如 ##）故意回退到正常 turn 提交——用户可以粘贴 Markdown 标题而不意外触发记忆写入。

模式 2：/memory 命令

子命令	效果
/memory	显示解析路径和当前内容
/memory show	同上，别名
/memory path	仅打印解析路径
/memory clear	用空标记替换文件
/memory edit	打印 ${VISUAL:-${EDITOR:-vi}} <path> 命令行
/memory help	显示命令帮助和当前路径

/memory edit 不启动编辑器——只打印命令，保持简单且与编辑器无关。

模式 3：remember 工具

当记忆启用时，模型获得 remember 工具：

{
  "name": "remember",
  "description": "Append a durable note to the user memory file...",
  "input_schema": {
    "type": "object",
    "properties": { "note": { "type": "string" } },
    "required": ["note"]
  }
}

自动批准——写入作用域限制在用户自己的记忆文件，不需要走标准写入审批流程。

注入位置

每轮系统提示携带额外的 <user_memory> 块：

<user_memory source="/Users/you/.codewhale/memory.md">
- (2026-06-01 10:00 UTC) prefer pytest over unittest
- (2026-06-01 10:30 UTC) this codebase uses 4-space indentation
</user_memory>

该块位于 volatile-content boundary 上方，保持在 DeepSeek 前缀缓存中跨 turn 复用。

文件加载与限制

• 文件路径：~/.codewhale/memory.md（可通过 memory_path 或 DEEPSEEK_MEMORY_PATH 覆盖）
• 每轮提示构建时读取——外部编辑器的修改在下一次 turn 生效，无需重启

• 100 KiB 的文件被加载但截断，并附加截断标记

问题与规避

陷阱：remember 工具被用于瞬时任务状态

如果模型用 remember 写入 “我正在编辑 foo.rs”，这会浪费上下文——因为这是瞬时状态，不是跨会话偏好。

规避：remember 工具的描述明确告诉模型不要这样做——只写入持久的、单句的备注。

陷阱：记忆与项目指令的混淆

记忆是用户级（跟随用户跨项目），项目指令是仓库级（跟随代码库）。

规避：

• 记忆：~/.codewhale/memory.md——个人偏好，跨仓库生效
• 项目指令：AGENTS.md / .codewhale/instructions.md——仓库约定，随代码库移动
• 当两者冲突时，Constitution Tier 5（项目指令）> Tier 7（记忆偏好）

陷阱：@path 导入不支持

记忆文件不支持 @path 导入/包含——如果需要更大的可复用指令束，应放在项目指令或技能中。

设计取舍

为什么记忆是用户级而非项目级

CodeWhale 选择用户级记忆的原因：

• 个人偏好（如”偏好 pytest”）跟随用户而非仓库
• 项目级约定通过 AGENTS.md 管理，随代码库移动
• 避免每个项目重复设置相同偏好

代价是换项目时需要区分”这是我的偏好”和”这是这个项目的约定”。

为什么 /memory edit 不启动编辑器

设计决策：只打印命令，不启动进程。原因：

• 保持 slash-command handler 简单
• 与用户选择的编辑器无关
• TUI 中启动外部编辑器需要 alt-screen 切换，增加复杂度

参考来源

• docs/MEMORY.md — 用户记忆功能文档
• 源码验证: crates/tui/src/tools/remember.rs — remember 工具实现