memory

Files (2)

• SKILL.md
• tools.ts

SKILL.md (first lines)

# Memory Skill — 主动记忆检索与管理

## 三层记忆结构

| 层 | 内容 | 存储方式 | 检索方式 |
|----|------|----------|----------|
| **Facts** | 长期事实：偏好、身份、基础设施、决策、TODO | SQLite facts + 向量 embedding | `search_memory` 主动检索，cross-encoder reranker 过滤噪音 |
| **Episodes** | session 摘要（100-200 字），session 结束或周期压缩时生成 | SQLite + 向量 embedding | `search_memory` 主动检索 |
| **Chunks** | 原始对话片段（user/assistant/tool） | SQLite + BM25 tokens + 向量 embedding | `search_memory` 主动检索 |
| **Semantic Graph** | 从 facts/episodes/chunks 抽取的实体与关系 | Graphiti + FalkorDB | `search_semantic_memory` 主动检索 fact edges + provenance |

所有记忆检索均通过 `search_memory` 工具主动触发，不再有自动注入的 framework 消息。

## 工具

### `search_memory(query, topK?)`
同时搜索三层记忆：
- **Facts**：向量余弦 + 时间衰减召回 top-30，经 cross-encoder reranker 二阶段重排，过滤低分噪音，返回 `facts[]`（含 `id`，可用于 supersede）
- **Episodes + Chunks**：向量检索 + BM25 三路 RRF 融合，再经 reranker 精排，返回 `results[]`，分数为 cross-encoder 输出的 0-1 实数

搜索写法建议：
- 优先写**完整语义句子**，不要只丢 1-2 个关键词。例：`Max 对动态记忆注入和 prompt cache 的偏好` 比 `记忆 注入 cache` 更好。
- 尽量带上**主体 + 主题 + 场景**。例：`Max 在记忆系统迁移这件事上的决策和原因`。
- 查配置/基础设施时，直接写**对象名 + 用途/位置**。例：`ollama 和 reranker 现在各跑在哪`。
- 查历史决策时，写成**一句自然语言问题**。例：`为什么不用普通 assistant/user 消息承载记忆召回`。
- 如果第一次结果太散，第二次就加限定词：时间、组件名、任务名、模型名、机器名。
- `topK` 适合在你已经知道主题较窄时调大；主题宽泛时先保持默认，避免噪声过多。

### `search_semantic_memory(query, maxFacts?)`
搜索 Graphiti 语义图，返回 entity/relation 抽取后的 fact edges，并附带来源 episode 与 MaxClaw 原始 `source_type/source_id`。

适合：
- 查实体/概念之间的关系：`MaxClaw Graphiti semantic memory provenance`
- 查某个系统组件和历史决策如何关联
- 验证语义抽取是否已经覆盖某类记忆

不适合：
- 找原始对话片段、旧摘要、SQLite facts 细节 —— 用 `search_memory`
- 更新/替换事实 —— 先用 `search_memory` 找 SQLite fact id，再用 `supersede_fact`

### `get_facts(category?)`
列出已存 facts，可按 category 过滤（如 Infrastructure / Process / Documentation）。  
返回每条 fact 的 `id`、`category`、`content`，用于核查或获取 id 以做 supersede。

### `supersede_fact(factId, newContent)`
将一条过时的 fact 替换为新内容：
- 旧 fact 标记为 superseded（保留历史可追溯）
- 新 fact 继承相同 category / confidence
- **使用前**：先通过 `search_memory` 或 `get_facts` 获取目标 fact 的 `id`

### `create_fact(content, category, confidence?)`
主动写入一条新 fact 到记忆系统。**这是后台 extractor 之外的唯一手动写入入口**。

- `content`：fact 完整陈述（自包含，不依赖外部 reference）
- `category`：开放字符串，可用 Preference / Process / Infrastructure / Decision / FailureMode / Identity 等，也可自由提议新分类
- `confidence`：0-1，默认 0.9

**何时手动调（而不是依赖被动抽取）：**
- ✅ Advisory failure mode 自我总结（如某种偏差被 Max 反复纠正）
- ✅ 跨会话稳定的约定/边界（如某类话题必须先 search_memory）
- ✅ 关键决策的结论（如"X 用 Y 方案而非 Z 的原因"）
- ✅ Max 当面强调但措辞具体、容易被 extractor 漏掉的偏好
- ❌ 日常偏好/配置/状态 — 这些后台 extractor 会自动抽取
- ❌ 一次性事实（明天就过时的）

**写入前先 `search_memory` 查重**；如存在等价但过时的 fact，用 `supersede_fact` 替换而非新增。

## 使用场景

- 用户问"你还记得 X 吗"时，主动 `search_memory` 检索相关记忆
- 需要确认某个历史决策、配置或旧对话细节时
- 发现当前上下文里的 fact 已过时 → `supersede_fact` 纠正
- 自己识别出值得长期保留但 extractor 抓不到的失败模式/约定 → `create_fact`
- 长时间后重新讨论某个话题，需要找回更深层的上下文

From maxesisn/maxclaw-oss, MIT.

More from maxesisn/maxclaw-oss