Skip to content

Commit b2716e9

Browse files
echoVicechoVic
committed
docs: add Auto Memory documentation
- guides/memory.md: new dedicated guide for Auto Memory system - guides/slash-commands.md: add /memory command with subcommands - reference/tool-list.md: add MemoryRead/MemoryWrite tools - changelog.md: add Unreleased section with all changes - _sidebar.md: add Auto Memory link to navigation
1 parent 2ae1dab commit b2716e9

5 files changed

Lines changed: 171 additions & 0 deletions

File tree

‎docs/_sidebar.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212

1313
* 使用指南
1414
* [Slash 命令](guides/slash-commands.md)
15+
* [Auto Memory](guides/memory.md)
1516
* [Subagents 系统](guides/subagents.md)
1617
* [Skills 系统](guides/skills.md)
1718
* [Hooks 钩子](guides/hooks.md)

‎docs/changelog.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,31 @@
33
All notable changes to this project will be documented in this file.
44

55

6+
## [Unreleased]
7+
8+
### ✨ 新功能
9+
10+
- **Auto Memory 系统** — Agent 跨会话持久化项目知识（构建命令、代码模式、调试洞察）
11+
- `MemoryRead` / `MemoryWrite` 工具：Agent 自动读写记忆文件，内置敏感数据过滤
12+
- `/memory` 命令：`list` / `show` / `edit` / `clear` 管理记忆文件
13+
- 启动时自动注入 MEMORY.md 前 200 行到 system prompt
14+
- 环境变量 `BLADE_AUTO_MEMORY=0` 可禁用
15+
16+
### 🐛 问题修复
17+
18+
- `createTool.execute()` 现在正确传递 `ExecutionContext` 到工具函数，修复 `context.workspaceRoot` 等始终为 undefined 的问题
19+
20+
### ♻️ 代码重构
21+
22+
- 清理 `PersistentStore` 废弃方法（`saveContext` / `saveSession` / `saveConversation`）
23+
- 新增 `ContextAssembler`：集中 JSONL 事件流到 ContextData 的重建逻辑，修复 tool calls 和 compaction summary 丢失问题
24+
- 修复 `ContextManager.saveCurrentSession()` 重复写入 JSONL 的问题
25+
26+
### ✅ 测试相关
27+
28+
- 新增 58 个单元测试（AutoMemoryManager 20 + MemoryTools 18 + ContextAssembler 20）
29+
30+
631
## [0.2.5] - 2026-02-16
732

833
### 🔧 其他更改

‎docs/guides/memory.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# 🧠 Auto Memory
2+
3+
Auto Memory 让 Agent 在工作中自动记录项目知识，跨会话持久化。新会话启动时自动加载历史记忆，Agent 不再"失忆"。
4+
5+
## 工作原理
6+
7+
1. **启动时加载** — 会话开始时，MEMORY.md 前 200 行自动注入 system prompt
8+
2. **工作中记录** — Agent 发现有价值的知识时，通过 MemoryWrite 工具保存
9+
3. **按需检索** — Agent 需要特定主题的详细信息时，通过 MemoryRead 工具读取
10+
11+
## 存储结构
12+
13+
记忆文件存储在项目专属目录下：
14+
15+
```
16+
~/.blade/projects/{escaped-path}/memory/
17+
├── MEMORY.md # 入口索引（启动时加载前 200 行）
18+
├── patterns.md # 项目模式（构建命令、代码风格）
19+
├── debugging.md # 调试洞察
20+
├── architecture.md # 架构笔记
21+
└── ... # Agent 按需创建的主题文件
22+
```
23+
24+
每个项目有独立的记忆空间，互不干扰。
25+
26+
## Agent 会记住什么
27+
28+
- 项目的构建、测试、lint 命令
29+
- 代码模式和约定
30+
- 调试过程中发现的解决方案
31+
- 架构决策和关键文件关系
32+
- 用户偏好和工作流习惯
33+
34+
## 安全机制
35+
36+
- **敏感数据过滤** — 自动拒绝包含 password、token、secret、api_key、private_key 的内容
37+
- **路径遍历防护** — 主题名不允许包含 `..` 或 `/`，防止写入任意路径
38+
- **索引行数限制** — MEMORY.md 加载上限 200 行，避免 system prompt 膨胀
39+
40+
## /memory 命令
41+
42+
在会话中使用 `/memory` 管理记忆文件：
43+
44+
| 命令 | 说明 |
45+
|------|------|
46+
| `/memory` | 列出所有记忆文件（等同于 `/memory list`） |
47+
| `/memory list` | 列出所有记忆文件及大小 |
48+
| `/memory show` | 显示 MEMORY.md 索引内容 |
49+
| `/memory show <topic>` | 显示指定主题文件内容 |
50+
| `/memory edit` | 用 `$EDITOR` 编辑 MEMORY.md |
51+
| `/memory edit <topic>` | 用 `$EDITOR` 编辑指定主题文件 |
52+
| `/memory clear` | 清空所有记忆文件 |
53+
54+
## 工具
55+
56+
### MemoryRead
57+
58+
读取记忆文件，Agent 在需要时自动调用。
59+
60+
```
61+
topic: "debugging" → 读取 debugging.md
62+
topic: "MEMORY" → 读取 MEMORY.md 索引
63+
topic: "_list" → 列出所有记忆文件
64+
```
65+
66+
### MemoryWrite
67+
68+
保存记忆内容，支持追加和覆盖模式。
69+
70+
```
71+
topic: "patterns"
72+
content: "## Build\npnpm build"
73+
mode: "append" → 追加到 patterns.md
74+
mode: "overwrite" → 覆盖 patterns.md
75+
```
76+
77+
## 配置
78+
79+
### 环境变量
80+
81+
```bash
82+
# 禁用 Auto Memory
83+
BLADE_AUTO_MEMORY=0
84+
85+
# 启用（默认）
86+
BLADE_AUTO_MEMORY=1
87+
```
88+
89+
## 最佳实践
90+
91+
- **MEMORY.md 是索引** — 保持简洁，详细内容放到主题文件
92+
- **让 Agent 自己学** — 不需要手动写记忆，Agent 会在工作中自动发现和记录
93+
- **定期检查** — 用 `/memory show` 看看 Agent 记了什么，用 `/memory edit` 修正不准确的内容
94+
- **项目初始化后** — 第一次在新项目中使用时，Agent 会逐步积累知识，几次会话后效果最佳
95+
96+
## 相关资源
97+
98+
- [Slash 命令](slash-commands.md) — 所有内置命令
99+
- [工具列表](../reference/tool-list.md) — MemoryRead / MemoryWrite 参数详情
100+
- [配置系统](../configuration/config-system.md) — 全局和项目级配置

‎docs/guides/slash-commands.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ Slash 命令是 Blade 的快捷操作入口，输入 `/` 触发建议，`Tab`
2323
| `/hooks` | - | 管理 Hooks |
2424
| `/resume` | - | 恢复历史会话 |
2525
| `/compact` | - | 手动压缩上下文 |
26+
| `/memory` | - | 管理项目记忆 |
2627
| `/git` | `/g` | Git 操作 |
2728
| `/login` | - | 登录 OAuth 服务 |
2829
| `/logout` | - | 登出 OAuth 服务 |
@@ -96,6 +97,24 @@ Git 仓库查询和 AI 辅助：
9697
/compact
9798
```
9899

100+
### /memory
101+
102+
管理项目的自动记忆系统。Agent 在工作中自动记录的项目知识（构建命令、代码模式、调试洞察等）会跨会话持久化。
103+
104+
```bash
105+
/memory # 等同于 /memory list
106+
/memory list # 列出所有记忆文件
107+
/memory show # 显示 MEMORY.md 索引内容
108+
/memory show <topic> # 显示指定主题文件内容
109+
/memory edit # 用 $EDITOR 编辑 MEMORY.md
110+
/memory edit <topic> # 用 $EDITOR 编辑指定主题文件
111+
/memory clear # 清空所有记忆文件
112+
```
113+
114+
记忆文件存储在 `~/.blade/projects/{project}/memory/` 目录下。
115+
116+
可通过环境变量 `BLADE_AUTO_MEMORY=0` 禁用自动记忆功能。
117+
99118
### /login
100119

101120
登录 OAuth 服务（Antigravity / Copilot）：

‎docs/reference/tool-list.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -282,6 +282,30 @@
282282

283283
## 系统工具
284284

285+
### MemoryRead
286+
287+
读取项目记忆文件。Agent 自动记录的项目知识跨会话持久化。
288+
289+
| 参数 | 类型 | 必填 | 说明 |
290+
|------|------|------|------|
291+
| `topic` | string | ✅ | 主题名（如 "debugging"）或 "_list" 列出所有文件，"MEMORY" 读取索引 |
292+
293+
**类型**: ReadOnly
294+
**返回**: 记忆文件内容或文件列表
295+
296+
### MemoryWrite
297+
298+
保存项目记忆。支持敏感数据过滤（password/token/secret/api_key/private_key）。
299+
300+
| 参数 | 类型 | 必填 | 说明 |
301+
|------|------|------|------|
302+
| `topic` | string | ✅ | 主题名（如 "patterns"），"MEMORY" 写入索引 |
303+
| `content` | string | ✅ | 要保存的内容 |
304+
| `mode` | string | | 写入模式：overwrite / append（默认 append） |
305+
306+
**类型**: Write
307+
**特性**: 自动过滤敏感数据，防止路径遍历
308+
285309
### AskUserQuestion
286310

287311
向用户提问并等待回复。
@@ -363,6 +387,8 @@ blade mcp list
363387
| Spec | UpdateTaskStatus | Write | 更新任务状态 |
364388
| Spec | ValidateSpec | ReadOnly | 验证 Spec 完整性 |
365389
| Spec | ExitSpecMode | Write | 退出 Spec 模式 |
390+
| 系统 | MemoryRead | ReadOnly | 读取项目记忆文件 |
391+
| 系统 | MemoryWrite | Write | 保存项目记忆 |
366392
| 系统 | AskUserQuestion | ReadOnly | 向用户提问 |
367393
| 系统 | Skill | Execute | 调用已注册的 Skill |
368394
| 系统 | SlashCommand | Execute | 执行 Slash 命令 |

0 commit comments

Comments
 (0)