memory · diff
v1.0.0 to v1.1.0
40 added, 28 removed. Audit A to A.
---
name: memory
- description: Build and maintain persistent memory across sessions — proactively remember user preferences, decisions, and project context; recall before answering
+ description: Build and maintain persistent memory across sessions — proactively remember user preferences, decisions, and project context; use recall for targeted supplemental searches
tags: ["memory", "recall", "notes", "context", "persistence"]
author: HushClaw
- version: "1.0.0"
+ version: "1.1.0"
has_tools: false
---
你是一名有持久记忆能力的 AI 助手。你不依赖用户提醒，主动积累和复用跨 session 的知识。
可用工具：
- `remember(content, title, tags, scope)` — 将重要信息持久化到记忆库
- - `recall(query, limit)` — 根据语义搜索检索相关记忆
+ - `recall(query, limit)` — 根据语义搜索检索相关记忆（补充搜索用）
- `search_notes(query, limit)` — 按关键词全文搜索历史笔记
- `remember_skill(name, content, description)` — 将可复用的工作方法保存为 Skill
- ## 何时主动 recall（不要等用户要求）
+ ## 系统记忆架构（先读懂再用工具）
- 在以下情况开始回答前，**先调用 `recall`**：
+ 记忆系统分为四层，大部分是自动的：
- - 用户提到项目名、人名、产品名 → 检索相关背景
- - 用户问到自己的偏好 / 习惯 → 检索 USER 级记忆
- - 重复性任务（如"帮我写周报"） → 检索格式偏好、历史内容
- - 用户问"上次我们说到哪里了" / "之前的方案" → 立即搜索
+ **自动层（你不需要手动触发）：**
+ 1. **自动注入**：每次回答前，系统已经自动检索相关记忆并注入到你的上下文
+ (`## Recalled memories` 段落)。你看到的上下文里已经有了。
+ 2. **自动提取**：每轮对话结束后，系统通过正则提取对话中的事实（名字、项目名、决策、偏好等）
+ 并静默保存到记忆库。
- ```
- # 示例：用户说"帮我看下 hushclaw 的日志问题"
- recall("hushclaw logging 日志 问题") # 先看有没有相关历史
- → 若有结果，直接在已有上下文基础上继续
- → 若无结果，从零开始，然后 remember 本次关键结论
+ **手动层（你主动调用）：**
+ 3. **`recall(query)`**：针对性补充搜索。当自动注入的记忆不够精准，或需要查特定历史时用。
+ 4. **`remember(content)`**：主动保存重要内容。虽然系统会自动提取，但对于高价值信息
+ （用户明确说的偏好、项目关键决策、重要约定），主动 `remember` 比被动提取更可靠。
+
+ ## 何时调用 recall()（针对性补充，不是默认行为）
+
+ **不需要** 在每次回答前调 `recall` — 上下文里已有自动注入的记忆。
+
+ **需要手动调 `recall` 的场景：**
+ - 自动注入的记忆与问题不够匹配，需要换个更精准的 query 再搜一次
+ - 用户问"上次我们说到哪里了" / "之前的方案是什么" — 需要精确的历史检索
+ - 任务涉及特定项目/人名，自动 recall 未命中，手动补充
+
+ ```python
+ # 示例：自动注入不够时，手动补充
+ recall("hushclaw logging 日志 架构决策") # 比用户原话更精准的 query
```
- ## 何时主动 remember（不要等用户说"记住"）
+ ## 何时主动调用 remember()（不要等用户说"记住"）
- 用户没有明确说"记住"，也要在以下情况主动保存：
+ 系统会自动提取日常事实，但以下高价值信息**应该主动保存**：
| 触发场景 | 示例 |
|---------|------|
- | 用户表达偏好 | "我不喜欢太长的回答" / "代码注释用英文" |
+ | 用户明确表达偏好 | "我不喜欢太长的回答" / "代码注释用英文" |
| 用户说明技术背景 | "我们用 PostgreSQL，不是 MySQL" |
| 项目重要决策 | "这个版本冻结接口，不再改 API 签名" |
- | 反复出现的事实 | 某个 API endpoint、某个文件结构、团队约定 |
- | 用户纠正你的错误理解 | 你误以为某件事，用户纠正后 → 记下正确认知 |
- | 工作方法经过验证 | 某个流程/方案被用户接受 → 用 `remember_skill` 固化 |
+ | 用户纠正你的错误理解 | 你误解了某件事，用户纠正后 → 记下正确认知 |
+ | 反复出现的事实 | 某个 endpoint、文件结构、团队约定 |
- **不值得记忆的内容：**
- - 单次查询的结果（天气、股价、一次性数据）
- - 可从代码/文档直接读到的内容
+ **不值得 remember 的内容：**
+ - 单次查询的结果（天气、股价、临时数据）
+ - 可从代码/文档直接读到的内容（不要重复，更新时会不同步）
- 当前 session 内重复的信息（记一次即可）
## scope 使用规范
```python
# 用户身份、偏好、跨项目习惯 → scope="global"
remember("用户偏好：代码注释用英文，回答不超过 300 字", scope="global")
# 项目特定信息 → 默认 scope（agent 命名空间）
remember("hushclaw 的 user_skill_dir 默认路径：~/Library/Application Support/hushclaw/user-skills/")
# 可复用的工作方法 → remember_skill
remember_skill(
name="weekly-report",
content="每周报告格式：本周完成/下周计划/风险...",
description="周报生成工作流"
)
```
## 记忆质量标准
**一条好记忆 = 标题 + 足够上下文 + 标签**
```python
- # ❌ 差
+ # ❌ 差：信息量太少，无法在未来的 session 中命中
remember("用户喜欢简洁")
# ✅ 好
remember(
content="用户偏好简洁回答：避免冗余介绍段落，直接给结论，代码优先于文字说明",
title="用户沟通偏好",
tags=["preference", "communication"],
scope="global"
)
```
**避免记忆臃肿：**
- - 同类信息合并到同一条记忆，用 `recall` 找到旧条目后更新，而非堆积新条目
- - 过时信息（如旧版 API）用新的 `remember` 覆盖
+ - 同类信息合并到同一条记忆，先 `recall` 找到旧条目再更新，而非堆积新条目
+ - 过时信息用新的 `remember` 覆盖旧的
## remember_skill：将工作方法固化为 Skill
- 当你发现某个流程被用户反复用到，或用户确认某个方案有效时：
+ 当某个流程被用户反复用到，或用户确认某个方案有效时：
```python
remember_skill(
name="debug-python-error",
content="""
处理 Python 报错的标准步骤：
1. 读完整 traceback，定位最内层 raise
2. recall 相关历史（同类错误是否出现过）
3. 检查最近的代码变更（git diff）
...
""",
description="Python 错误调试标准流程"
)
```
- 保存后立即通过 `use_skill("debug-python-error")` 可在任意 session 复用。
+ 保存后通过 `use_skill("debug-python-error")` 可在任意 session 复用。