mnemonics

Mnemonics：通过 Historian 管理记忆

重要：必须使用 @historian

记忆工具只能通过 @historian 子 Agent 使用。你不能直接调用以下工具：

• memory_remember - 创建或更新记忆
• memory_recall - 搜索并检索记忆
• memory_forget - 删除记忆
• memory_list_types - 列出可用的记忆类型
• memory_sync - 重建搜索索引

始终委派给 historian：

@historian remember that we decided on PostgreSQL for the database
@historian what did we decide about authentication?

记忆类型

类型	用途	示例
architectural-decision	系统架构选择	“使用 PostgreSQL 和只读副本实现扩展”
design-decision	UI/UX 决策	“仪表板采用卡片布局，桌面端显示 3 列”
learning	经验与发现	“Bun 原生支持 TS，无需构建步骤”
user-preference	用户偏好	“用户偏好深色模式，使用制表符而非空格”
project-preference	团队约定	“我们使用约定式提交，必须进行 PR 审查”
issue	已知问题	“尚未实现速率限制，正在 #42 跟踪”
context	常规背景信息（默认）	“项目于 2026 年 2 月启动，MVP 目标为第二季度”
recurring-pattern	可复用模式	“错误处理：用 try/catch 包裹，返回 {error}”
conventions-pattern	编码规范	“使用命名导出，避免默认导出”

**注意：**项目可通过配置定义自定义记忆类型。始终使用 @historian list all memory types available 查看当前项目的完整类型列表。

何时委派给 Historian

记住（创建/更新）：

• 做出重要的架构或设计决策后
• 用户表达了其工作方式方面的偏好
• 发现了有关代码库或工具的重要信息
• 学到了应在不同会话间保留的经验

回忆（搜索/检索）：

• 开始新会话时 → 回忆相关背景信息
• 用户询问“我们对 X 做了什么决定？”
• 需要确认是否已经做过某项决策
• 查找已知问题或模式

忘记（删除）：

• 用户想删除过时或错误的记忆
• 清理重复或无关条目

同步（重建索引）：

• 手动编辑 .mnemonics/ 中的记忆文件后
• 搜索结果似乎过时时

示例提示词

记忆

@historian remember that we decided on JWT auth with 15-min expiry
@historian save this learning: Bun handles TypeScript natively without compilation
@historian note that the user prefers minimal UI animations
@historian store this as an architectural-decision: we're using event sourcing for the audit log

回忆

@historian what did we decide about authentication?
@historian recall any known issues with the API
@historian what are my preferences for this project?
@historian show all architectural decisions
@historian find memories about database choices

管理

@historian list all memory types available
@historian forget the memory about the old API design
@historian sync the index to include recent memory files

工作原理

1. 记忆存储在 .mnemonics/{type}/{title}.md 中，采用带 YAML frontmatter 的 Markdown 文件格式
2. 索引会自动构建，使用 qmd（混合 BM25 + 向量搜索）
3. Historian 负责分类、去重和语义搜索
4. 文件适合纳入 Git 管理——提交这些文件即可与团队共享

最佳实践

1. 标题要具体——使用“qmd-cli-for-writes”，而不是“重要决策”
2. 让 historian 负责分类——它会先进行搜索，避免重复
3. 决策前先回忆——检查是否已有相关决策
4. 提交记忆文件——它们是项目知识的一部分