# Orca 记忆系统实施计划

**基于设计文档**: `thoughts/shared/designs/2025-05-11-orca-memory-final-design.md`
**实施方式**: 增量升级（在已有 v1 基础上扩展）
**预估工期**: 5-7 天

---

## Phase 1: 数据库 Schema 扩展（第 1 天）

### 1.1 新增 `memory_usage_log` 表

**文件**: `pkg/session/sqlite_store.go` — `initSchema()` 方法

```go
// 在 initSchema() 中添加
schema += `
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,
    was_referenced INTEGER NOT NULL DEFAULT 0,
    used_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (memory_id) REFERENCES long_term_memories(id) ON DELETE CASCADE
);
CREATE INDEX IF NOT EXISTS idx_usage_memory ON memory_usage_log(memory_id);
CREATE INDEX IF NOT EXISTS idx_usage_session ON memory_usage_log(session_id);
`
```

**依赖**: 无
**测试**: 验证表创建成功，外键约束生效

---

### 1.2 新增 `dialogue_buffer` 表

**文件**: `pkg/session/sqlite_store.go` — `initSchema()` 方法

```go
// 在 initSchema() 中添加
schema += `
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
);
CREATE INDEX IF NOT EXISTS idx_buffer_session ON dialogue_buffer(session_id, created_at);
`
```

**依赖**: 无
**测试**: 验证表创建成功

---

### 1.3 扩展 `long_term_memories` 表

**文件**: `pkg/session/sqlite_store.go`

当前表缺少 `weight`, `tags`, `archived` 字段。由于是 ALTER TABLE，需要小心处理：

```go
// 在 initSchema() 中修改 long_term_memories 定义
// 或添加迁移逻辑
migrations := []string{
    `ALTER TABLE long_term_memories ADD COLUMN weight REAL NOT NULL DEFAULT 1.0`,
    `ALTER TABLE long_term_memories ADD COLUMN tags TEXT`,
    `ALTER TABLE long_term_memories ADD COLUMN archived INTEGER NOT NULL DEFAULT 0`,
}
```

**注意**: SQLite 支持 ADD COLUMN，但有限制（不能加 UNIQUE / PRIMARY KEY）

**依赖**: 无
**测试**: 验证迁移后数据完整性

---

## Phase 2: 配置扩展（第 1-2 天）

### 2.1 扩展 Config 结构体

**文件**: `internal/config/config.go`

```go
type Config struct {
    // ... 现有字段 ...
    
    Memory      MemoryConfig      // 新增
    MemoryAgent MemoryAgentConfig // 新增
}

type MemoryConfig struct {
    Enabled              bool   `toml:"enabled"`
    MaxHistory           int    `toml:"max_history"`
    
    ShortTerm ShortTermConfig `toml:"short_term"`
    LongTerm  LongTermConfig  `toml:"long_term"`
    Inject    InjectConfig    `toml:"inject"`
}

type ShortTermConfig struct {
    MaxItems             int `toml:"max_items"`
    CompressionThreshold int `toml:"compression_threshold"`
}

type LongTermConfig struct {
    Enabled          bool    `toml:"enabled"`
    VectorIndex      bool    `toml:"vector_index"`
    MaxReturn        int     `toml:"max_return"`
    ArchiveThreshold float64 `toml:"archive_threshold"`
}

type InjectConfig struct {
    FirstRoundEmpty bool   `toml:"first_round_empty"`
    ShortTermCount  int    `toml:"short_term_count"`
    LongTermTrigger string `toml:"long_term_trigger"`
    MinQueryLength  int    `toml:"min_query_length"`
}

type MemoryAgentConfig struct {
    Enabled  bool            `toml:"enabled"`
    Provider string          `toml:"provider"`
    Model    string          `toml:"model"`
    APIKey   string          `toml:"api_key"`
    BaseURL  string          `toml:"base_url"`
    Timeout  string          `toml:"timeout"`
    Extract  ExtractConfig   `toml:"extract"`
    Summarize SummarizeConfig `toml:"summarize"`
}

type ExtractConfig struct {
    BatchSize      int     `toml:"batch_size"`
    MaxFacts       int     `toml:"max_facts"`
    MinConfidence  float64 `toml:"min_confidence"`
    AutoTag        bool    `toml:"auto_tag"`
}

type SummarizeConfig struct {
    Enabled       bool `toml:"enabled"`
    TriggerTokens int  `toml:"trigger_tokens"`
}
```

**依赖**: Phase 1 完成
**测试**: 验证 TOML 解析正确

---

### 2.2 更新 config.toml.example

**文件**: `config.toml.example`

添加完整的 `[memory]` 和 `[memory_agent]` 示例配置。

**依赖**: 2.1 完成

---

## Phase 3: MemoryManager 扩展（第 2-3 天）

### 3.1 添加权重管理方法

**文件**: `pkg/session/memory_manager.go`

```go
// RecordMemoryUsage 记录记忆使用并更新权重
func (mm *MemoryManager) RecordMemoryUsage(memoryID int64, sessionID, query string, referenced bool) error

// UpdateMemoryWeight 更新单条记忆权重
func (mm *MemoryManager) UpdateMemoryWeight(memoryID int64, delta float64) error

// ArchiveLowWeightMemories 归档低权重记忆
func (mm *MemoryManager) ArchiveLowWeightMemories(threshold float64) (int, error)

// GetCoreMemories 获取核心记忆（高权重）
func (mm *MemoryManager) GetCoreMemories(minWeight float64) ([]LongTermMemory, error)

// GetArchivedMemories 获取已归档记忆
func (mm *MemoryManager) GetArchivedMemories() ([]LongTermMemory, error)
```

**依赖**: Phase 1, Phase 2
**测试**: 验证权重计算正确，归档逻辑生效

---

### 3.2 添加对话缓冲管理

**文件**: `pkg/session/memory_manager.go`

```go
// BufferDialogue 缓冲对话
func (mm *MemoryManager) BufferDialogue(sessionID, userQuery, assistantResponse string) error

// GetBufferedDialogues 获取缓冲的对话
func (mm *MemoryManager) GetBufferedDialogues(sessionID string, limit int) ([]Dialogue, error)

// ClearBuffer 清空缓冲
func (mm *MemoryManager) ClearBuffer(sessionID string) error

// ShouldExtract 检查是否触发提取
func (mm *MemoryManager) ShouldExtract(sessionID string) (bool, error)
```

**依赖**: Phase 1
**测试**: 验证缓冲写入、读取、清空

---

### 3.3 增强记忆注入逻辑

**文件**: `pkg/session/memory_manager.go`

```go
// ShouldInjectMemory 判断是否注入记忆
func (mm *MemoryManager) ShouldInjectMemory(query string, msgCount int) bool

// BuildMemoryContextWithStats 构建记忆上下文（增强版）
// 现有方法需要增强：支持 first_round_empty, min_query_length
```

修改 `BuildMemoryContextWithStats` 支持配置参数：
- `first_round_empty`: msgCount == 0 时返回空
- `min_query_length`: len(query) < threshold 时返回空
- `long_term_trigger`: 检测技术关键词

**依赖**: Phase 2
**测试**: 验证各种注入条件

---

### 3.4 添加长期记忆写入

**文件**: `pkg/session/memory_manager.go`

```go
// AddLongTermMemoryWithEmbedding 添加长期记忆并生成向量
func (mm *MemoryManager) AddLongTermMemoryWithEmbedding(content, memoryType string, tags []string, confidence float64) error

// UpdateLongTermMemory 更新长期记忆
func (mm *MemoryManager) UpdateLongTermMemory(id int64, updates map[string]interface{}) error
```

**依赖**: Phase 1
**测试**: 验证写入 + 向量生成

---

## Phase 4: MemoryExtractorAgent（第 3-4 天）

### 4.1 创建 Agent Prompt 文件

**文件**: `~/.orca/agents/memory_extractor.md`

内容来自设计文档，需要安装到用户目录。

**文件**: `pkg/actor/memory_extractor_prompt.go`（内嵌默认 prompt，作为 fallback）

```go
package actor

const DefaultMemoryExtractorPrompt = `...`
```

**依赖**: 无
**测试**: 验证 prompt 加载

---

### 4.2 实现 MemoryExtractorAgent

**文件**: `pkg/actor/memory_extractor_agent.go`

```go
package actor

type MemoryExtractorAgent struct {
    *SubAgent
    config MemoryAgentConfig
}

// NewMemoryExtractorAgent 创建提取 Agent
func NewMemoryExtractorAgent(id string, llmBackend llm.LLM, cfg MemoryAgentConfig) (*MemoryExtractorAgent, error)

// ExtractFacts 从对话中提取事实
func (mea *MemoryExtractorAgent) ExtractFacts(dialogues []Dialogue) ([]Fact, error)

// parseFactJSON 解析提取结果
func parseFactJSON(content string) ([]Fact, error)
```

**类型定义**:
```go
type Dialogue struct {
    UserQuery         string
    AssistantResponse string
}

type Fact struct {
    Content    string
    Type       string   // fact/preference/project
    Tags       []string
    Confidence float64
    Replace    *string  // 被替换的旧事实
}
```

**依赖**: Phase 2, Phase 3
**测试**: 验证提取逻辑，JSON 解析

---

### 4.3 集成到 Kernel

**文件**: `pkg/kernel/kernel.go`

在 Kernel 初始化时创建 MemoryExtractorAgent：

```go
// 在 NewWithConfig() 中
if cfg.MemoryAgent.Enabled {
    kernel.memoryExtractor, err = actor.NewMemoryExtractorAgent(
        "memory_extractor",
        kernel.llmBackend,
        cfg.MemoryAgent,
    )
}
```

**依赖**: 4.2
**测试**: 验证 Kernel 启动

---

## Phase 5: LLMAgent 集成（第 4-5 天）

### 5.1 修改 buildLLMMessages

**文件**: `pkg/actor/llm_agent.go`

增强 `buildLLMMessages()` 方法：

```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 a.memoryManager != nil {
        msgCount := a.sessionMgr.GetMessageCount(a.sessionID)
        if a.memoryManager.ShouldInjectMemory(query, msgCount) {
            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
}
```

**依赖**: Phase 3
**测试**: 验证注入条件，Token 预算

---

### 5.2 修改消息处理流程

**文件**: `pkg/actor/llm_agent.go`

在消息保存后添加记忆维护：

```go
func (a *LLMAgent) handleUserMessage(ctx context.Context, msg Message) error {
    // ... 原有逻辑 ...
    
    // 保存消息（原有）
    a.sessionMgr.SaveMessage(...)
    
    // 记忆维护（新增）
    if a.memoryManager != nil {
        a.memoryManager.MaintainSessionMemory(a.sessionID, query, response)
    }
    
    return nil
}
```

**依赖**: Phase 3
**测试**: 验证 STM 生成，缓冲写入

---

### 5.3 添加异步提取触发

**文件**: `pkg/actor/llm_agent.go` 或 `pkg/session/memory_manager.go`

```go
// triggerExtraction 异步触发事实提取
func (mm *MemoryManager) triggerExtraction(sessionID string) {
    dialogues, _ := mm.GetBufferedDialogues(sessionID, mm.config.Extract.BatchSize)
    
    go func() {
        // 调用 MemoryExtractorAgent
        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.Extract.MinConfidence {
                mm.AddLongTermMemoryWithEmbedding(...)
            }
        }
        
        mm.ClearBuffer(sessionID)
    }()
}
```

**依赖**: Phase 4
**测试**: 验证异步执行，错误处理

---

## Phase 6: 权重反馈系统（第 5 天）

### 6.1 记忆引用检测

**文件**: `pkg/session/memory_manager.go`

```go
// DetectMemoryReference 检测 Agent 回复是否引用了某条记忆
func (mm *MemoryManager) DetectMemoryReference(response string, memories []LongTermMemory) []int64 {
    // 简单实现：检查记忆中关键词是否出现在回复中
    // 高级实现：使用 Embedding 相似度
}
```

**依赖**: Phase 3
**测试**: 验证检测准确率

---

### 6.2 自动归档任务

**文件**: `pkg/session/memory_manager.go`

```go
// RunMaintenance 运行记忆维护任务
func (mm *MemoryManager) RunMaintenance() error {
    // 1. 归档低权重记忆
    mm.ArchiveLowWeightMemories(mm.config.LongTerm.ArchiveThreshold)
    
    // 2. 清理过期 STM
    mm.Cleanup()
    
    // 3. 其他维护...
}
```

**依赖**: Phase 3
**测试**: 验证归档逻辑

---

## Phase 7: CLI 命令（第 5-6 天）

### 7.1 添加 CLI 命令

**文件**: `cmd/orca/main.go` 或新建 `cmd/orca/memory.go`

```go
// orca memory list
// orca memory search "query"
// orca memory delete <id>
// orca memory clean
// orca memory stats
// orca memory export > backup.json
// orca memory import < backup.json
```

**依赖**: Phase 3
**测试**: 验证命令执行

---

## Phase 8: 测试与优化（第 6-7 天）

### 8.1 单元测试

| 模块 | 测试项 | 文件 |
|------|--------|------|
| Schema | 表创建、迁移 | `pkg/session/sqlite_store_test.go` |
| Config | TOML 解析 | `internal/config/config_test.go` |
| Weight | 权重计算、归档 | `pkg/session/memory_manager_test.go` |
| Buffer | 缓冲写入、清空 | `pkg/session/memory_manager_test.go` |
| Extractor | 事实提取、JSON 解析 | `pkg/actor/memory_extractor_test.go` |
| Injection | 注入条件、Token 预算 | `pkg/actor/llm_agent_test.go` |

### 8.2 集成测试

```go
// test_memory_system_v2.go
func TestMemorySystemV2(t *testing.T) {
    // 1. 创建会话
    // 2. 发送消息（验证 STM 生成）
    // 3. 发送 5 条消息（验证 LTM 提取触发）
    // 4. 查询长期记忆（验证向量检索）
    // 5. 验证权重变化
    // 6. 验证归档逻辑
}
```

### 8.3 性能测试

| 指标 | 目标 | 测试方法 |
|------|------|---------|
| 向量检索 | < 100ms | BenchmarkVectorSearch |
| Embedding 缓存 | > 95% 命中 | BenchmarkEmbeddingCache |
| 权重更新 | < 10ms | BenchmarkWeightUpdate |
| 整体延迟 | < 200ms | BenchmarkMemoryInjection |

---

## 依赖图

```
Phase 1 (Schema)
    │
    ├──→ Phase 2 (Config)
    │       │
    │       ├──→ Phase 3 (MemoryManager)
    │       │       │
    │       │       ├──→ Phase 4 (ExtractorAgent)
    │       │       │       │
    │       │       │       └──→ Phase 5 (LLMAgent)
    │       │       │
    │       │       └──→ Phase 6 (Weight System)
    │       │
    │       └──→ Phase 7 (CLI)
    │
    └──→ Phase 8 (Test)
```

---

## 风险与缓解

| 风险 | 可能性 | 影响 | 缓解 |
|------|--------|------|------|
| Schema 迁移失败 | 中 | 高 | 备份数据库，测试迁移脚本 |
| MemoryExtractor 幻觉 | 高 | 中 | 高置信度阈值，人工抽查 |
| 权重系统不准确 | 中 | 低 | 提供手动调整 CLI |
| 性能退化 | 低 | 中 | 监控，及时优化索引 |
| 向后兼容 | 中 | 高 | 保留旧配置解析逻辑 |

---

## 验收标准

- [ ] 所有新增表创建成功
- [ ] 配置解析正确，默认值合理
- [ ] STM 自动生成（每轮对话）
- [ ] LTM 批量提取（每 5 轮）
- [ ] 向量检索正常（语义相似度）
- [ ] 权重自动更新（引用检测）
- [ ] 低权重记忆自动归档
- [ ] CLI 命令可用
- [ ] 单元测试覆盖率 > 80%
- [ ] 集成测试通过
- [ ] 性能指标达标