---
title: "feat: AgentKit 分层记忆系统 — SOUL/USER/MEMORY/DAILY 注入"
status: completed
created: 2026-06-08
plan_type: feat
depth: standard
---

## Summary

为 AgentKit 实现分层记忆注入系统，参考 Hermes/OpenClaw 架构，在每次会话启动时将 SOUL.md（Agent 人格）、USER.md（用户档案）、MEMORY.md（Agent 工作笔记）、DAILY.md（最近日志）注入 system prompt，并提供 MemoryTool 让 Agent 在对话中读写记忆。采用 TDD 方式开发。

## Problem Frame

当前 `agentkit chat` 的 system prompt 是硬编码的一句话，Agent 无法：
1. 拥有持久人格（名字、性格、说话方式）
2. 记住用户信息（称呼、习惯、职业）
3. 跨会话保留工作笔记
4. 回顾近期决策和对话摘要

虽然已有 `memory/` 模块（Working/Episodic/Semantic），但这些是面向 Pipeline 编排的底层记忆，不是面向 Chat 场景的"人格+档案+笔记"注入。

## Requirements

- **R1**: SOUL.md — Agent 人格定义，每次会话必须加载
- **R2**: USER.md — 用户档案，每次会话必须加载
- **R3**: MEMORY.md — Agent 工作笔记，每次会话必须加载，Agent 可通过工具修改
- **R4**: DAILY.md — 最近 2 天日志，每次会话自动加载，Agent 可通过工具追加
- **R5**: MemoryTool — Agent 可在对话中 add/replace/remove 记忆条目
- **R6**: 文件存储在 `~/.agentkit/` 目录下，首次运行自动创建默认 SOUL.md
- **R7**: 容量上限 — SOUL ~2000 字符、USER ~1400 字符、MEMORY ~2200 字符、DAILY ~1000 字符/天
- **R8**: 注入方式 — 会话开始时一次性注入 system prompt，会话内不变（利于 KV 缓存）
- **R9**: 与现有 `agentkit chat` 命令集成

## Key Technical Decisions

### KTD1: 记忆文件格式 — Markdown sections

每个 .md 文件使用 `## Section` 格式组织内容，方便 Agent 通过 MemoryTool 的 `replace` 操作精确替换某个 section，而非重写整个文件。

```
## 身份
我是小王，一个专业的 AI 助手。

## 性格
友好、耐心、注重细节

## 说话方式
简洁专业，偶尔使用比喻
```

### KTD2: 注入格式 — 分段注入 system prompt

将记忆内容作为 system prompt 的结构化段落注入，每段用明确的标记分隔：

```
<agent-identity>
[SOUL.md content]
</agent-identity>

<user-profile>
[USER.md content]
</user-profile>

<agent-notes>
[MEMORY.md content]
</agent-notes>

<recent-activity>
[DAILY.md content]
</recent-activity>

[原始 system prompt 或默认指令]
```

### KTD3: MemoryTool 操作模型 — section 级别 CRUD

- `memory_add(section, content)` — 追加内容到指定 section（不存在则创建）
- `memory_replace(file, section, old_text, new_text)` — 精确替换 section 内的文本
- `memory_remove(file, section)` — 删除整个 section
- `memory_read(file)` — 读取整个文件内容

file 参数: `soul` | `user` | `memory` | `daily`

### KTD4: 日志自动生成 — 会话结束时摘要

会话结束时（用户 /quit 或 Ctrl+C），自动调用 LLM 生成当天日志摘要追加到 DAILY.md。保留最近 2 天日志，更早的自动归档。

### KTD5: 存储路径 — `~/.agentkit/memories/`

```
~/.agentkit/
├── SOUL.md              # Agent 人格
├── memories/
│   ├── USER.md          # 用户档案
│   ├── MEMORY.md        # 工作笔记
│   └── daily/
│       ├── 2026-06-07.md
│       └── 2026-06-08.md
└── agentkit.yaml        # 配置文件（已存在）
```

## Implementation Units

### U1. MemoryFile — 记忆文件读写与容量管理

**Goal:** 实现记忆文件的读写、容量限制、section 级别操作

**Dependencies:** None

**Files:**
- `src/agentkit/memory/profile.py` — MemoryFile 类
- `tests/unit/test_memory_profile.py` — 测试

**Approach:**
- `MemoryFile` 类：封装单个 .md 文件的读写、section 解析、容量检查
- `read()` / `write()` — 读写整个文件
- `read_section(name)` / `add_section(name, content)` / `replace_section(name, old, new)` / `remove_section(name)` — section 级别操作
- `trim_to_budget(char_budget)` — 超出容量时从末尾裁剪（保留前面的 section）
- 文件不存在时返回空字符串，不抛异常

**Execution note:** TDD — 先写测试再实现

**Test scenarios:**
- 读取不存在的文件返回空字符串
- 写入并读回完整内容
- 解析 `## Section` 格式，read_section 返回指定 section 内容
- add_section 追加新 section
- replace_section 精确替换 section 内文本
- remove_section 删除指定 section
- 超出 char_budget 时 trim_to_budget 裁剪
- 空文件 read_section 返回空

**Verification:** 所有测试通过

---

### U2. MemoryStore — 多文件记忆管理器

**Goal:** 管理 SOUL/USER/MEMORY/DAILY 四类记忆文件，提供统一的加载和注入接口

**Dependencies:** U1

**Files:**
- `src/agentkit/memory/profile.py` — MemoryStore 类（同文件）
- `tests/unit/test_memory_profile.py` — 追加测试

**Approach:**
- `MemoryStore(base_dir)` — 接受 `~/.agentkit` 路径
- `load_all()` — 加载所有记忆文件，返回 `MemorySnapshot` dataclass
- `build_system_prompt(snapshot, base_prompt)` — 将记忆注入 system prompt
- `get_file(file_key)` — 返回指定 MemoryFile（file_key: soul/user/memory/daily）
- `load_daily_logs(days=2)` — 加载最近 N 天日志
- `archive_old_dailies(days=2)` — 归档超过 N 天的日志
- `ensure_defaults()` — 首次运行创建默认 SOUL.md
- `MemorySnapshot` dataclass: soul, user, memory, daily, total_chars

**Execution note:** TDD

**Test scenarios:**
- MemoryStore 初始化，目录不存在时自动创建
- load_all() 返回 MemorySnapshot
- build_system_prompt() 正确注入所有段落
- build_system_prompt() 无记忆文件时只返回 base_prompt
- ensure_defaults() 创建默认 SOUL.md
- load_daily_logs() 加载最近 2 天日志
- archive_old_dailies() 归档旧日志
- 容量超限时 build_system_prompt 仍能工作（trim）

**Verification:** 所有测试通过

---

### U3. MemoryTool — Agent 可调用的记忆操作工具

**Goal:** 实现 Agent 在对话中读写记忆的工具

**Dependencies:** U1, U2

**Files:**
- `src/agentkit/tools/memory_tool.py` — MemoryTool 类
- `tests/unit/test_memory_tool.py` — 测试

**Approach:**
- 继承 `Tool` 基类
- `memory_add(file, section, content)` — 追加内容
- `memory_replace(file, section, old_text, new_text)` — 替换内容
- `memory_remove(file, section)` — 删除 section
- `memory_read(file)` — 读取文件
- file 参数限定为 `soul` | `user` | `memory` | `daily`
- 操作后自动 trim 到容量上限
- 返回操作结果和当前文件内容摘要

**Execution note:** TDD

**Test scenarios:**
- memory_add 创建新 section
- memory_add 追加到已有 section
- memory_replace 精确替换文本
- memory_replace old_text 不存在时返回错误
- memory_remove 删除 section
- memory_read 返回文件内容
- 无效 file 参数返回错误
- 操作后内容不超容量上限

**Verification:** 所有测试通过

---

### U4. Chat 集成 — 记忆注入 + MemoryTool + 日志生成

**Goal:** 将记忆系统集成到 `agentkit chat` 命令

**Dependencies:** U2, U3

**Files:**
- `src/agentkit/cli/chat.py` — 修改
- `tests/unit/test_chat_memory_integration.py` — 测试

**Approach:**
- `_chat_async()` 启动时：
  1. 初始化 `MemoryStore(base_dir=~/.agentkit)`
  2. 调用 `ensure_defaults()` 创建默认文件
  3. `load_all()` 加载记忆
  4. `build_system_prompt(snapshot, base_prompt)` 构建完整 system prompt
  5. 将 `MemoryTool(memory_store)` 加入 tools 列表
- 会话结束时：
  1. 调用 LLM 生成当天对话摘要
  2. 追加到 DAILY.md
  3. 归档旧日志
- `/clear` 命令不清除记忆文件，只清除会话历史

**Execution note:** TDD

**Test scenarios:**
- chat 启动时自动加载记忆注入 system prompt
- 无记忆文件时使用默认 SOUL.md
- MemoryTool 在对话中可用
- 会话结束时生成日志摘要
- /clear 不影响记忆文件
- 记忆跨 /clear 会话持久化

**Verification:** 所有测试通过，手动 `agentkit chat` 验证

---

### U5. Onboarding 集成 — 首次引导创建 SOUL.md

**Goal:** 在 onboarding 向导中增加 Agent 人格配置步骤

**Dependencies:** U2

**Files:**
- `src/agentkit/cli/onboarding.py` — 修改
- `tests/unit/test_onboarding.py` — 追加测试

**Approach:**
- onboarding 最后一步增加可选的 Agent 人格配置：
  - Agent 名字（默认 "AgentKit"）
  - 性格描述（默认 "专业、友好、注重细节"）
  - 说话方式（默认 "简洁清晰"）
- 写入默认 SOUL.md
- 可跳过（使用默认值）

**Execution note:** TDD

**Test scenarios:**
- onboarding 生成默认 SOUL.md
- 自定义名字写入 SOUL.md
- 跳过时使用默认值

**Verification:** 所有测试通过

## Scope Boundaries

### In Scope
- SOUL/USER/MEMORY/DAILY 四层记忆文件
- MemoryFile section 级别 CRUD
- MemoryStore 统一加载和注入
- MemoryTool Agent 可调用工具
- Chat 命令集成
- Onboarding 集成
- 日志自动生成

### Out of Scope
- 向量检索记忆（已有 EpisodicMemory）
- Redis/PostgreSQL 后端（已有 WorkingMemory/SemanticMemory）
- 多 Agent 共享记忆（后续）
- 记忆版本控制（后续）
- 记忆加密（后续）

### Deferred to Follow-Up Work
- 记忆导入/导出命令
- 记忆搜索（在大量笔记中搜索）
- 与 EpisodicMemory 的整合（将 DAILY 日志同步到 Episodic）

## Open Questions

None — 所有设计决策已在 KTD 中明确。

## Risks & Mitigations

| 风险 | 缓解措施 |
|------|---------|
| system prompt 过长占用 token | 容量上限 + trim_to_budget |
| Agent 恶意修改 SOUL.md | SOUL.md 可设为只读（后续），当前信任 Agent |
| 日志文件无限增长 | archive_old_dailies 自动归档，保留最近 2 天 |
| 文件并发写入冲突 | 单进程 chat 场景无并发问题 |