Vibe-Trading Memory 机制：架构与实现原理

def increment(self, key: str) -> int: ... def to_summary(self) -> str: """Generate a state summary for the LLM. ... This summary survives context compression and helps the LLM remember what it was working on. ... """

### 2.2 在 AgentLoop 中的生命周期

1. **`run_dir` 的确定**（在构造消息列表之前）  
   - 若 `memory.run_dir` 已存在且路径在磁盘上存在，则沿用。  
   - 否则通过 `RunStateStore.create_run_dir` 新建，并写回 `self.memory.run_dir`。

2. **工具参数中的 `run_dir` 归一化**  
   `_normalize_tool_run_dir` 使用 `memory.run_dir` 作为基准，把相对路径（如 `"."`、子目录名）解析为绝对路径，保证工具在一致根目录下读写。

3. **计数更新**  
   每次工具结果落盘后调用 `_update_memory(tool_name)` → `self.memory.increment(tool_name)`。

4. **与 `_auto_compact` 的配合**  
   压缩对话时保留原始 `system` 消息对象，但在压缩产生的「交接摘要」用户消息末尾追加 `Current agent state:\n{state_summary}`，其中 `state_summary = self.memory.to_summary()`。这样**即使长对话被折叠，工作区状态仍有一条独立注入路径**。

**注意**：初始 system 里的 `{memory_summary}` 是**构造 `build_messages` 那一刻**的快照；中间迭代的工具计数不会自动写回该条 system，除非触发 `_auto_compact`（会在压缩块中再次注入 `to_summary()`）。

相关代码位置：`agent/src/agent/loop.py`（`run_dir` 与 `ContextBuilder` 创建、`_auto_compact` 内 `state_summary`、`_update_memory`）。

---

## 3. 持久记忆（PersistentMemory）

### 3.1 设计目标与存储布局

- **零外部依赖**：不依赖向量库或数据库，纯文件系统。
- **默认目录**：`~/.vibe-trading/memory/`（常量 `MEMORY_BASE`）。
- **文件角色**：  
  - `MEMORY.md`：人类可读的**索引**（列表形式，带链接与一行描述）。  
  - 多个 `{memory_type}_{slug}.md`：**具体记忆条目**，带 YAML-like frontmatter + 正文。

Storage layout: ~/.vibe-trading/memory/ +-- MEMORY.md # Index (< 200 lines) +-- user_prefs.md # Individual memory entries with YAML frontmatter

### 3.2 内存中的「快照」语义

`PersistentMemory` 在 `__init__` 时调用 `_load_snapshot()`：若存在 `MEMORY.md`，读取全文后**只保留前 `MAX_INDEX_LINES`（200）行**作为 `_snapshot`，且之后**不会在 `add`/`remove` 时更新该快照**。

设计意图（源码注释）：

- **会话开始时**把索引注入 system prompt，有利于 **prompt 缓存稳定**。
- **磁盘**会即时反映 `save`/`forget`，但**当前会话内的 snapshot 字符串不变**；**下一次**新建 `PersistentMemory()` 会重新加载。

Design:

• Frozen snapshot injected into system prompt at session start (preserves prompt cache).
• Disk writes via add()/remove() update files immediately but do NOT change the snapshot.
• Next session picks up the updated state.

### 3.3 条目模型与扫描

`MemoryEntry` 为不可变数据类，聚合路径、标题、描述、`memory_type`、正文（截断至 `MAX_ENTRY_CHARS = 8000`）、`mtime`。

`_scan_entries()` 遍历目录下所有 `*.md`，跳过 `MEMORY.md`，用与技能文件共用的 `parse_frontmatter`（`agent/src/agent/frontmatter.py`）解析 frontmatter，得到结构化元数据 + body。

### 3.4 写入：`add`

1. **文件名 slug**：`name.lower().strip()` 后经正则清洗：保留字母数字、`_`、`-` 及 **CJK 范围**（避免纯 CJK 标题被压成相同 slug 导致静默覆盖）。  
2. 文件名：`{memory_type}_{slug}.md`（slug 最长 60）。  
3. Frontmatter 字段：`name`、`description`（默认用 title）、`type`。  
4. 写文件后调用 `_update_index`：在 `MEMORY.md` 中按标题查找并替换行，或追加新行；整体仍受 `MAX_INDEX_LINES` 截断。

### 3.5 删除：`remove`

按**精确标题** `entry.title == name` 匹配，删除对应文件并 `_rebuild_index()` 全量重建索引。

### 3.6 检索：`find_relevant`

**非向量检索**，基于 `_tokenize` 的集合交集打分：

- **ASCII**：长度 ≥ 3 的 `[a-zA-Z0-9]+` 小写 token（**下划线不作为 token 的一部分**，从而 `mcp_wiring_test` 可被 “mcp wiring” 这类查询命中）。  
- **CJK**：单字纳入 token 集合。  
- 对每条目：`meta_tokens = tokenize(title + description)`，`body_tokens = tokenize(body)`。  
- **得分** = `|query ∩ meta| * METADATA_WEIGHT(2.0) + |query ∩ body| * 1.0`。  
- 排序：得分降序，同分按 `modified_at` 降序（较新优先）。  
- 默认最多 `MAX_RESULTS = 5` 条（`ContextBuilder` 里自动召回用 3）。

return _SYSTEM_PROMPT.format( ... memory_summary=self.memory.to_summary(), memory_section=memory_section, current_datetime=now.strftime("%A, %B %d, %Y %H:%M (local)"), )

系统提示中还包含对模型的**行为指引**：在适当时机使用 `remember` 工具保存偏好与洞见。

### 4.2 用户消息侧的「自动召回」

`build_messages` 在追加本轮用户消息前，若存在 `persistent_memory`，则对用户原文做 `find_relevant(user_message, max_results=3)`，若有结果，将摘要包在 `<recalled-memories>...</recalled-memories>` 中并置于用户消息**前缀**。

设计意图：

- **保持 system prompt 稳定**（利于缓存）；  
- **按查询动态**注入相关记忆，避免把全部正文塞进 system。

异常被吞掉并打 debug 日志，避免召回失败阻断主流程。

---

## 5. 工具层：`remember` 与注册表依赖注入

### 5.1 RememberTool

- 工具名：`remember`。  
- `action`：`save` | `recall` | `forget`。  
- `save` 需要 `title` + `content`，可选 `memory_type`（`user` / `feedback` / `project` / `reference`）。  
- `recall` 需要 `query`。  
- `forget` 需要 `title`（与持久层按标题删除一致）。  
- `is_readonly = False`：参与写盘，在 `AgentLoop` 的批处理里会走**串行**路径。

构造器可注入 `PersistentMemory`；若未注入则自行 `PersistentMemory()`（默认目录）。实现见 `agent/src/tools/remember_tool.py`。

### 5.2 `build_registry` 的单例共享

`build_registry(persistent_memory=pm)` 时，对 `RememberTool` **特殊处理**：用同一个 `pm` 实例注册，保证「上下文里的 `PersistentMemory`」与「工具写盘的 `PersistentMemory`」是同一对象。

### 5.3 服务端与 CLI 的装配

- **`agent/src/session/service.py` `_run_with_agent`**：`pm = PersistentMemory()`，`AgentLoop(..., persistent_memory=pm)` 且 `build_registry(persistent_memory=pm, ...)`。  
- **`agent/cli.py`**：同样模式，并可设置 `agent.memory.run_dir` 覆盖。

---

## 6. 端到端数据流（概念架构）

9. 小结