491 lines
17 KiB
Markdown
491 lines
17 KiB
Markdown
---
|
||
date: 2025-05-11
|
||
topic: "Orca 完整记忆系统 + Agent 进化方案"
|
||
status: validated
|
||
---
|
||
|
||
# Orca 完整记忆系统 + Agent 进化方案
|
||
|
||
## 一、系统架构总览
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 用户消息 │
|
||
└──────────────────────┬──────────────────────────────────────┘
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 智能注入层（规则驱动，零 LLM 开销） │
|
||
│ • 首轮对话 → 不带记忆 │
|
||
│ • 第 2+ 轮 → 自动注入短期记忆（3条） │
|
||
│ • 技术讨论 → 额外注入长期记忆（2条） │
|
||
└──────────────────────┬──────────────────────────────────────┘
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 记忆查询层（按需加载） │
|
||
│ • 短期记忆：SQLite + 语义检索（缓存命中 130x 加速） │
|
||
│ • 长期记忆：SQLite + 独立向量索引（vec_long_term_memories） │
|
||
└──────────────────────┬──────────────────────────────────────┘
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ LLM Agent 处理消息 │
|
||
└──────────────────────┬──────────────────────────────────────┘
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 记忆维护层（后台异步） │
|
||
│ • 短期记忆：即时摘要保存（现有逻辑） │
|
||
│ • 长期记忆：MemoryExtractorAgent 批量提取（每 5 轮一次） │
|
||
└──────────────────────┬──────────────────────────────────────┘
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 进化层（权重系统） │
|
||
│ • 记忆被引用 → 权重 +1 │
|
||
│ • 记忆未引用 → 权重 -0.5 │
|
||
│ • 权重 < 0.3 → 归档 │
|
||
│ • 权重 > 5.0 → 核心记忆 │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 二、配置架构（config.toml）
|
||
|
||
```toml
|
||
# ========== 主 LLM 配置 ==========
|
||
provider = "deepseek"
|
||
|
||
[deepseek]
|
||
base_url = "https://api.deepseek.com/v1"
|
||
model = "deepseek-v4-flash"
|
||
api_key = "sk-xxx"
|
||
timeout = "120s"
|
||
|
||
# ========== Embedding 配置 ==========
|
||
[embedding]
|
||
provider = "siliconflow"
|
||
model = "Pro/BAAI/bge-m3"
|
||
dimensions = 1024
|
||
max_context = 8192
|
||
|
||
[siliconflow]
|
||
api_key = "sk-xxx"
|
||
base_url = "https://api.siliconflow.cn/v1"
|
||
|
||
# ========== 记忆系统配置（新增） ==========
|
||
[memory]
|
||
enabled = true # 记忆系统总开关
|
||
max_history = 100 # 工作记忆最大轮数
|
||
|
||
[memory.short_term]
|
||
max_items = 10 # 最多保留 10 条短期记忆
|
||
compression_threshold = 200 # 超过 200 字自动压缩
|
||
|
||
[memory.long_term]
|
||
enabled = true # 长期记忆开关
|
||
vector_index = true # 启用向量索引
|
||
max_return = 2 # 每次最多返回 2 条
|
||
archive_threshold = 0.3 # 权重低于此值归档
|
||
|
||
[memory.inject]
|
||
first_round_empty = true # 首轮不带记忆
|
||
short_term_count = 3 # 默认注入 3 条短期记忆
|
||
long_term_trigger = "technical" # 技术讨论触发长期记忆
|
||
min_query_length = 10 # query 最短长度才查长期记忆
|
||
|
||
# ========== MemoryExtractorAgent 配置（新增） ==========
|
||
[memory_agent]
|
||
enabled = true
|
||
provider = "deepseek" # 可独立配置，默认继承主 LLM
|
||
model = "deepseek-v4-flash" # 可用便宜模型，如 deepseek-chat
|
||
api_key = "" # 留空继承 deepseek.api_key
|
||
base_url = "" # 留空继承 deepseek.base_url
|
||
timeout = "60s"
|
||
|
||
[memory_agent.extract]
|
||
batch_size = 5 # 每 5 轮提取一次
|
||
max_facts = 10 # 每次最多提取 10 个事实
|
||
min_confidence = 0.6 # 置信度阈值
|
||
auto_tag = true # 自动打标签
|
||
|
||
[memory_agent.summarize]
|
||
enabled = true # 启用对话总结
|
||
trigger_tokens = 4000 # 超过此 token 触发总结
|
||
```
|
||
|
||
---
|
||
|
||
## 三、Agent 描述文件
|
||
|
||
**文件位置**： `~/.orca/agents/memory_extractor.md`
|
||
|
||
```markdown
|
||
# Memory Extractor Agent
|
||
|
||
你是一个专门从对话中提取用户信息的 Agent。你的工作是将非结构化的对话转化为结构化的长期记忆。
|
||
|
||
## 任务
|
||
|
||
分析给定的对话记录，提取以下类型的信息：
|
||
|
||
1. **事实 (fact)**：客观信息
|
||
- 工作：公司、职位、技术栈、行业
|
||
- 技术：擅长语言、框架偏好、架构经验
|
||
- 个人：教育背景、所在城市（仅用户明确提及）
|
||
|
||
2. **偏好 (preference)**：主观倾向
|
||
- 回答风格：简洁/详细/代码示例/架构图
|
||
- 技术偏好：语言、数据库、部署方式
|
||
- 沟通偏好：正式/ casual
|
||
|
||
3. **项目 (project)**：当前工作
|
||
- 项目名称、技术方案、当前阶段、遇到的挑战
|
||
|
||
## 输出格式
|
||
|
||
只输出 JSON，不要任何解释：
|
||
|
||
```json
|
||
{
|
||
"facts": [
|
||
{
|
||
"content": "用户在电商公司担任后端工程师",
|
||
"type": "fact",
|
||
"tags": ["工作", "后端", "电商"],
|
||
"confidence": 0.95,
|
||
"replace": null
|
||
},
|
||
{
|
||
"content": "用户偏好简洁的技术回答，不要过多解释",
|
||
"type": "preference",
|
||
"tags": ["沟通风格", "偏好"],
|
||
"confidence": 0.85,
|
||
"replace": "用户喜欢详细的回答"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 规则
|
||
|
||
- confidence < 0.6 的事实不输出
|
||
- 如果新事实与旧事实冲突：
|
||
- 在 replace 字段填入被替换的旧事实 content
|
||
- 只替换同一 type + 同一 tags 的事实
|
||
- 不猜测、不推断，只提取用户明确表达的信息
|
||
- 标签从预设列表选择：工作、技术、偏好、项目、沟通风格、行业
|
||
```
|
||
|
||
---
|
||
|
||
## 四、数据表设计
|
||
|
||
### 现有表（已验证）
|
||
|
||
- `main_messages` — 工作记忆
|
||
- `short_term_memories` — 短期记忆
|
||
- `subagent_messages` — 子 Agent 对话
|
||
|
||
### 新增表
|
||
|
||
```sql
|
||
-- 长期记忆向量索引（核心新增）
|
||
CREATE VIRTUAL TABLE IF NOT EXISTS vec_long_term_memories USING vec0(
|
||
memory_id INTEGER PRIMARY KEY,
|
||
embedding FLOAT[1024]
|
||
);
|
||
|
||
-- 长期记忆主表（扩展）
|
||
CREATE TABLE IF NOT EXISTS long_term_memories (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
content TEXT NOT NULL UNIQUE,
|
||
memory_type TEXT NOT NULL DEFAULT 'fact', -- fact/preference/project
|
||
tags TEXT, -- JSON 数组 ["工作", "技术"]
|
||
confidence REAL NOT NULL DEFAULT 0.8,
|
||
weight REAL NOT NULL DEFAULT 1.0, -- 动态权重
|
||
access_count INTEGER NOT NULL DEFAULT 0,
|
||
last_accessed DATETIME,
|
||
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||
archived INTEGER NOT NULL DEFAULT 0 -- 0=活跃, 1=归档
|
||
);
|
||
|
||
-- 记忆使用日志（用于权重计算）
|
||
CREATE TABLE IF NOT EXISTS memory_usage_log (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
memory_id INTEGER NOT NULL,
|
||
session_id TEXT NOT NULL,
|
||
query TEXT NOT NULL, -- 用户原始 query
|
||
was_referenced INTEGER NOT NULL DEFAULT 0, -- 是否被 Agent 引用
|
||
used_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
|
||
);
|
||
|
||
-- 对话缓冲（批量提取用）
|
||
CREATE TABLE IF NOT EXISTS dialogue_buffer (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
session_id TEXT NOT NULL,
|
||
user_query TEXT NOT NULL,
|
||
assistant_response TEXT NOT NULL,
|
||
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
## 五、核心流程设计
|
||
|
||
### 5.1 消息处理流程（动态注入）
|
||
|
||
```go
|
||
func (a *LLMAgent) buildLLMMessages(query string) []llm.Message {
|
||
messages := make([]llm.Message, 0)
|
||
|
||
// 1. System prompt（原有）
|
||
if a.systemPrompt != "" {
|
||
messages = append(messages, llm.Message{Role: "system", Content: a.systemPrompt})
|
||
}
|
||
|
||
// 2. Tool prompt（原有）
|
||
if toolPrompt := a.buildToolPrompt(); toolPrompt != "" {
|
||
messages = append(messages, llm.Message{Role: "system", Content: toolPrompt})
|
||
}
|
||
|
||
// 3. 记忆注入（新增：智能判断）
|
||
if shouldInjectMemory(query, a.sessionMgr.GetMessageCount(a.sessionID)) {
|
||
ctx, stats := a.memoryManager.BuildMemoryContextWithStats(a.sessionID, query)
|
||
if ctx != "" {
|
||
messages = append(messages, llm.Message{Role: "system", Content: ctx})
|
||
log.Printf("[memory] Injected: short=%d, long=%d, tokens=%d",
|
||
stats.ShortTermCount, stats.LongTermCount, stats.TotalTokens)
|
||
}
|
||
}
|
||
|
||
// 4. 对话历史（原有）
|
||
// ...
|
||
|
||
return messages
|
||
}
|
||
|
||
func shouldInjectMemory(query string, msgCount int) bool {
|
||
if msgCount == 0 {
|
||
return false // 首轮不带记忆
|
||
}
|
||
if len(query) < 10 {
|
||
return false // 太短不查
|
||
}
|
||
return true
|
||
}
|
||
```
|
||
|
||
### 5.2 记忆维护流程（批量提取）
|
||
|
||
```go
|
||
func (mm *MemoryManager) MaintainSessionMemory(sessionID, userQuery, assistantResponse string) {
|
||
// 1. 保存短期记忆（即时）
|
||
summary := fmt.Sprintf("用户问：%s\n回答：%s",
|
||
userQuery, truncateString(assistantResponse, 100))
|
||
mm.AddShortTermMemory(sessionID, summary)
|
||
|
||
// 2. 缓冲对话（用于批量提取）
|
||
mm.bufferDialogue(sessionID, userQuery, assistantResponse)
|
||
|
||
// 3. 检查是否触发批量提取
|
||
if mm.shouldExtract() {
|
||
mm.triggerExtraction(sessionID)
|
||
}
|
||
}
|
||
|
||
func (mm *MemoryManager) triggerExtraction(sessionID string) {
|
||
dialogues := mm.flushBuffer(sessionID)
|
||
|
||
// 异步调用 MemoryExtractorAgent
|
||
go func() {
|
||
facts, err := mm.extractor.ExtractFacts(dialogues)
|
||
if err != nil {
|
||
log.Printf("[memory] Extraction failed: %v", err)
|
||
return
|
||
}
|
||
|
||
for _, fact := range facts {
|
||
if fact.Confidence >= mm.config.MinConfidence {
|
||
mm.AddLongTermMemory(fact)
|
||
}
|
||
}
|
||
}()
|
||
}
|
||
```
|
||
|
||
### 5.3 权重反馈流程（自动进化）
|
||
|
||
```go
|
||
func (mm *MemoryManager) recordMemoryUsage(memoryID int64, sessionID, query string, referenced bool) {
|
||
// 1. 记录使用日志
|
||
mm.store.Exec(
|
||
"INSERT INTO memory_usage_log (memory_id, session_id, query, was_referenced) VALUES (?, ?, ?, ?)",
|
||
memoryID, sessionID, query, referenced,
|
||
)
|
||
|
||
// 2. 更新权重
|
||
delta := 0.5
|
||
if !referenced {
|
||
delta = -0.3
|
||
}
|
||
|
||
mm.store.Exec(
|
||
"UPDATE long_term_memories SET weight = weight + ?, access_count = access_count + 1, last_accessed = ? WHERE id = ?",
|
||
delta, time.Now(), memoryID,
|
||
)
|
||
|
||
// 3. 检查归档
|
||
mm.archiveLowWeightMemories()
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 六、MemoryExtractorAgent 实现
|
||
|
||
```go
|
||
package actor
|
||
|
||
type MemoryExtractorAgent struct {
|
||
*SubAgent
|
||
config ExtractConfig
|
||
}
|
||
|
||
func NewMemoryExtractorAgent(id string, llmBackend llm.LLM, cfg ExtractConfig) *MemoryExtractorAgent {
|
||
prompt := loadAgentPrompt("memory_extractor") // 读取 ~/.orca/agents/memory_extractor.md
|
||
|
||
sa := NewSubAgent(id, llmBackend,
|
||
WithSubAgentRole("memory_extractor"),
|
||
WithSubAgentSystemPrompt(prompt),
|
||
)
|
||
|
||
return &MemoryExtractorAgent{SubAgent: sa, config: cfg}
|
||
}
|
||
|
||
func (mea *MemoryExtractorAgent) ExtractFacts(dialogues []Dialogue) ([]Fact, error) {
|
||
// 格式化对话为 prompt
|
||
var sb strings.Builder
|
||
sb.WriteString("请分析以下对话记录，提取用户的关键信息：\n\n")
|
||
for i, d := range dialogues {
|
||
sb.WriteString(fmt.Sprintf("--- 对话 %d ---\n", i+1))
|
||
sb.WriteString(fmt.Sprintf("用户：%s\n", d.UserQuery))
|
||
sb.WriteString(fmt.Sprintf("助手：%s\n\n", d.AssistantResponse))
|
||
}
|
||
|
||
msg := bus.Message{Type: bus.MsgTypeTaskRequest, Content: sb.String()}
|
||
resp, err := mea.Process(context.Background(), msg)
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
|
||
return parseFactJSON(resp.Content)
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 七、实施路线图
|
||
|
||
### Phase 1: 基础记忆层（1-2 天）
|
||
- [ ] 扩展 `long_term_memories` 表（添加 weight, tags, archived 字段）
|
||
- [ ] 创建 `vec_long_term_memories` 向量索引表
|
||
- [ ] 创建 `memory_usage_log` 使用日志表
|
||
- [ ] 创建 `dialogue_buffer` 对话缓冲表
|
||
- [ ] 修改 config.toml 解析，支持 `[memory]` 和 `[memory_agent]` 段
|
||
|
||
### Phase 2: 记忆注入层（1-2 天）
|
||
- [ ] 实现 `shouldInjectMemory()` 智能判断逻辑
|
||
- [ ] 修改 `buildLLMMessages()` 注入记忆上下文
|
||
- [ ] 实现短期记忆检索（现有逻辑优化）
|
||
- [ ] 实现长期记忆向量检索（语义搜索）
|
||
- [ ] 添加 Embedding 缓存层（130x 加速）
|
||
|
||
### Phase 3: MemoryExtractorAgent（2-3 天）
|
||
- [ ] 创建 `~/.orca/agents/memory_extractor.md` 提示词文件
|
||
- [ ] 实现 `MemoryExtractorAgent` 结构体
|
||
- [ ] 实现 `ExtractFacts()` 批量提取逻辑
|
||
- [ ] 实现对话缓冲和批量触发机制
|
||
- [ ] 集成到 `MaintainSessionMemory()` 流程
|
||
|
||
### Phase 4: 权重进化系统（1-2 天）
|
||
- [ ] 实现 `recordMemoryUsage()` 权重反馈
|
||
- [ ] 实现记忆引用检测（判断 Agent 是否使用了某条记忆）
|
||
- [ ] 实现自动归档逻辑（权重 < 0.3）
|
||
- [ ] 实现核心记忆标记（权重 > 5.0）
|
||
- [ ] 添加 `orca memory` CLI 命令（list, stats, clean）
|
||
|
||
### Phase 5: 测试与优化（1-2 天）
|
||
- [ ] 单元测试：记忆检索、权重计算、事实提取
|
||
- [ ] 集成测试：端到端对话流程
|
||
- [ ] 性能测试：Embedding 缓存命中率、向量检索延迟
|
||
- [ ] 调优：权重阈值、提取频率、注入策略
|
||
|
||
---
|
||
|
||
## 八、预期效果
|
||
|
||
| 指标 | 目标值 |
|
||
|------|--------|
|
||
| 记忆命中率 | > 80%（相关查询能命中有效记忆） |
|
||
| Token 消耗 | 增加 < 15%（记忆注入的额外开销） |
|
||
| 长期记忆检索 | < 100ms（向量搜索 + 缓存） |
|
||
| 自动学习 | 每 5 轮对话自动提取 2-5 个事实 |
|
||
| 记忆质量 | 人工抽查 > 90% 准确 |
|
||
| 成本增加 | Embedding API 调用 ≈ ¥0.01/千次 |
|
||
|
||
---
|
||
|
||
## 九、关键决策总结
|
||
|
||
| 决策 | 方案 | 理由 |
|
||
|------|------|------|
|
||
| 提取频率 | 每 5 轮批量提取 | 平衡实时性与 API 成本 |
|
||
| 提取模型 | 复用主 LLM（可独立配置） | 降低复杂度，留优化空间 |
|
||
| 意图分类 | 规则驱动（首轮/长度/技术词） | 零 LLM 开销，可预测 |
|
||
| 预加载 | 无，按需查询 | 避免无关记忆污染上下文 |
|
||
| 聚类 | 标签 + 类型，无自动聚类 | 人工可理解，可控 |
|
||
| 反馈机制 | 引用检测 + 权重调整 | 简单有效，可解释 |
|
||
|
||
---
|
||
|
||
## 评审意见处理
|
||
|
||
| 评审意见 | 处理方式 |
|
||
|---------|---------|
|
||
| vec0 兼容性 | ✅ 已确认可用，保留原方案 |
|
||
| Agent 演化系统 | ✅ 用户明确要求保留权重系统 |
|
||
| 异步处理 | ✅ 使用 goroutine 异步调用 MemoryExtractorAgent |
|
||
| 记忆衰减 | ✅ weight 字段 + archive_threshold 实现 |
|
||
| Token 预算 | ✅ 通过 max_return 和 short_term_count 控制 |
|
||
| 降级策略 | ✅ 配置项 enabled = true/false 可完全关闭 |
|
||
| 混合检索 | ⚠️ 当前纯向量检索，后续可添加 FTS5 |
|
||
| 嵌入模型版本化 | ⚠️ 当前固定 bge-m3，后续可扩展 |
|
||
|
||
---
|
||
|
||
## 附录
|
||
|
||
### A. 嵌入模型配置
|
||
|
||
**固定使用**：硅基流动 Pro/BAAI/bge-m3
|
||
- 维度：1024
|
||
- 最大上下文：8192
|
||
- 优势：中文优化，质量高
|
||
|
||
### B. 权重计算示例
|
||
|
||
```
|
||
初始：weight = 1.0
|
||
被引用 5 次：1.0 + 5*0.5 = 3.5
|
||
未被引用 3 次：3.5 - 3*0.3 = 2.6
|
||
超过 5.0 → 标记为核心记忆
|
||
低于 0.3 → 归档（不删除，可恢复）
|
||
```
|
||
|
||
### C. 降级路径
|
||
|
||
```
|
||
Level 1: 向量检索 + 权重排序（正常）
|
||
Level 2: 纯 SQL 检索（向量服务故障）
|
||
Level 3: 仅短期记忆（长期记忆关闭）
|
||
Level 4: 无记忆（memory.enabled = false）
|
||
``` |