记忆

Logic Memory 设计与实施计划

Aster Logic Memory(第四类记忆)的架构、实施路线与验收标准

Aster SDK Logic Memory 通用框架设计与实施计划

执行摘要

Aster Agent SDK 框架层 实现通用的 Logic Memory 系统,作为第四种 Memory 类型(与 Text/Working/Semantic Memory 并列)。提供开箱即用的用户偏好学习和行为模式记忆能力,支持任意应用场景(创作、对话、编程、客服等)。

设计原则

  • 通用性优先:框架层提供通用机制,应用层定义业务逻辑
  • 最小侵入:通过 Middleware 自动捕获,无需应用层手动调用
  • 可扩展性:支持自定义 Memory 类型、Pattern Matcher、Storage Backend
  • 生产就绪:完整的监控、测试、文档

参考案例:YunJin 写作平台(验证框架的实际可用性)


一、架构设计

1.1 整体架构图

┌─────────────────────────────────────────────────────────────────┐
│                     Aster Agent SDK                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                  Memory System                           │   │
│  ├─────────────────────────────────────────────────────────┤   │
│  │  Text Memory  │ Working Memory │ Semantic Memory │ NEW  │   │
│  │  (agent.md)   │ (临时状态)      │ (向量检索)      │ Logic│   │
│  │               │                 │                 │Memory│   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │              Logic Memory Framework                      │   │
│  ├─────────────────────────────────────────────────────────┤   │
│  │                                                           │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │   │
│  │  │  Capture     │  │   Storage    │  │  Retrieval   │  │   │
│  │  │  捕获层      │  │   存储层     │  │  检索层      │  │   │
│  │  └─────────────┘  └──────────────┘  └──────────────┘  │   │
│  │         │                  │                  │         │   │
│  │         ▼                  ▼                  ▼         │   │
│  │  ┌─────────────────────────────────────────────────┐  │   │
│  │  │         Logic Memory Manager (核心)            │  │   │
│  │  └─────────────────────────────────────────────────┘  │   │
│  │                                                           │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │            Middleware Stack                              │   │
│  ├─────────────────────────────────────────────────────────┤   │
│  │  LogicMemoryMiddleware (NEW)                            │   │
│  │  - 订阅 EventBus                                         │   │
│  │  - 自动捕获用户交互                                      │   │
│  │  - 注入 Memory 到 System Prompt                          │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                   │
└─────────────────────────────────────────────────────────────────┘

          ▲                                     ▲
          │                                     │
          │  应用层自定义                       │  应用层调用
          │  (MemoryType, PatternMatcher)      │  (初始化配置)
          │                                     │

┌─────────────────────────────────────────────────────────────────┐
│                    Application Layer                │
├─────────────────────────────────────────────────────────────────┤
│  - 定义业务相关的 Memory 类型 (WritingPreference, etc.)         │
│  - 实现自定义 PatternMatcher (识别用户修改模式)                 │
│  - 配置 LogicMemoryMiddleware                                   │
└─────────────────────────────────────────────────────────────────┘

1.2 核心组件设计

组件 1: LogicMemory - 核心数据结构

// pkg/memory/logic/types.go

// LogicMemory 逻辑记忆(通用结构)
type LogicMemory struct {
    // 基础字段
    ID            string
    Namespace     string  // 租户隔离(user:123, team:456, global)
    Scope         MemoryScope  // Session/User/Global

    // Memory 类型(应用层定义)
    Type          string  // "user_preference", "behavior_pattern", etc.
    Category      string  // 分类(可选)

    // Memory 内容
    Key           string  // 唯一标识(如 "writing_tone_preference")
    Value         any     // 值(结构化数据)
    Description   string  // 人类可读描述(用于 Prompt 注入)

    // 溯源(复用现有 Provenance)
    Provenance    *MemoryProvenance

    // 统计
    AccessCount   int
    LastAccessed  time.Time

    // 元信息
    Metadata      map[string]any  // 扩展字段
    CreatedAt     time.Time
    UpdatedAt     time.Time
}

// MemoryScope 记忆作用域
type MemoryScope string

const (
    ScopeSession  MemoryScope = "session"  // 单次会话
    ScopeUser     MemoryScope = "user"     // 用户级别
    ScopeGlobal   MemoryScope = "global"   // 全局(跨用户)
)

组件 2: LogicMemoryStore - 存储接口(可扩展)

// pkg/memory/logic/store.go

// LogicMemoryStore 存储接口(类似现有 BackendProtocol)
type LogicMemoryStore interface {
    // 基础 CRUD
    Save(ctx context.Context, memory *LogicMemory) error
    Get(ctx context.Context, namespace, key string) (*LogicMemory, error)
    Delete(ctx context.Context, namespace, key string) error
    List(ctx context.Context, namespace string, filters ...Filter) ([]*LogicMemory, error)

    // 高级查询
    SearchByType(ctx context.Context, namespace, memoryType string) ([]*LogicMemory, error)
    SearchByScope(ctx context.Context, namespace string, scope MemoryScope) ([]*LogicMemory, error)
    GetTopK(ctx context.Context, namespace string, k int, orderBy OrderBy) ([]*LogicMemory, error)

    // 统计
    IncrementAccessCount(ctx context.Context, namespace, key string) error
    GetStats(ctx context.Context, namespace string) (*MemoryStats, error)

    // 生命周期
    Prune(ctx context.Context, criteria PruneCriteria) (int, error)  // 清理低价值 Memory
}

// 内置实现
type PostgreSQLLogicStore struct { /* 基于 PostgreSQL */ }
type RedisLogicStore struct { /* 基于 Redis(简单场景) */ }
type InMemoryLogicStore struct { /* 基于内存(测试用) */ }

组件 3: PatternMatcher - 模式识别(可扩展)

// pkg/memory/logic/matcher.go

// PatternMatcher 模式识别接口(应用层实现)
type PatternMatcher interface {
    // 从事件中识别 Memory
    MatchEvent(ctx context.Context, event Event) ([]*LogicMemory, error)

    // 支持的事件类型
    SupportedEventTypes() []string
}

// Event 通用事件结构
type Event struct {
    Type      string         // "user_message", "tool_result", "user_feedback", etc.
    Source    string         // 来源(agent_id, user_id)
    Data      map[string]any // 事件数据
    Timestamp time.Time
}

// 应用层示例:YunJin 的 PatternMatcher
type YunJinPatternMatcher struct {
    // 自定义识别逻辑
}

func (m *YunJinPatternMatcher) MatchEvent(ctx context.Context, event Event) ([]*LogicMemory, error) {
    switch event.Type {
    case "user_revision":
        return m.matchRevisionPattern(event.Data)
    case "user_feedback":
        return m.matchFeedbackPattern(event.Data)
    default:
        return nil, nil
    }
}

组件 4: LogicMemoryManager - 核心管理器

// pkg/memory/logic/manager.go

// LogicMemoryManager 核心管理器
type LogicMemoryManager struct {
    store           LogicMemoryStore
    matchers        []PatternMatcher  // 支持多个 Matcher
    provenance      *MemoryProvenance
    consolidation   *ConsolidationEngine  // 复用现有 Consolidation
    confidence      *ConfidenceCalculator // 复用现有 Confidence
}

// RecordMemory 记录新 Memory(主动调用)
func (m *LogicMemoryManager) RecordMemory(ctx context.Context, memory *LogicMemory) error

// ProcessEvent 处理事件,自动识别和记录 Memory(被动触发)
func (m *LogicMemoryManager) ProcessEvent(ctx context.Context, event Event) error

// RetrieveMemories 检索 Memory(用于 Prompt 注入)
func (m *LogicMemoryManager) RetrieveMemories(
    ctx context.Context,
    namespace string,
    filters ...Filter,
) ([]*LogicMemory, error)

// ConsolidateMemories 合并冗余 Memory(定期任务)
func (m *LogicMemoryManager) ConsolidateMemories(ctx context.Context, namespace string) error

// PruneMemories 清理低价值 Memory(定期任务)
func (m *LogicMemoryManager) PruneMemories(ctx context.Context, criteria PruneCriteria) error

组件 5: LogicMemoryMiddleware - 自动捕获和注入

// pkg/middleware/logic_memory.go

// LogicMemoryMiddleware Logic Memory 中间件
type LogicMemoryMiddleware struct {
    *BaseMiddleware
    manager      *logic.LogicMemoryManager
    eventBus     *events.EventBus
    config       *LogicMemoryConfig
}

// LogicMemoryConfig 配置
type LogicMemoryConfig struct {
    // 存储配置
    Store            logic.LogicMemoryStore
    Matchers         []logic.PatternMatcher  // 应用层注入

    // 捕获配置
    EnableCapture    bool
    CaptureChannels  []types.AgentChannel  // Progress/Control/Monitor

    // 注入配置
    EnableInjection  bool
    InjectionPoint   string  // "system_prompt", "user_prompt", "both"
    MaxMemories      int     // TopK
    MinConfidence    float64 // 最低置信度

    // 性能配置
    AsyncCapture     bool
    CacheTTL         time.Duration
}

// OnAgentStart Agent 启动时订阅事件
func (m *LogicMemoryMiddleware) OnAgentStart(ctx context.Context, agentID string) error {
    // 订阅 EventBus
    m.eventBus.OnControl("*", m.handleControlEvent)
    m.eventBus.OnMonitor("*", m.handleMonitorEvent)
    // ...
}

// WrapModelCall 注入 Memory 到 Prompt
func (m *LogicMemoryMiddleware) WrapModelCall(next ModelCallFunc) ModelCallFunc {
    return func(ctx context.Context, msgs []types.Message, cfg *types.CallConfig) (types.Message, error) {
        // 1. 检索相关 Memory
        namespace := getNamespaceFromContext(ctx)
        memories, _ := m.manager.RetrieveMemories(ctx, namespace,
            logic.WithTopK(m.config.MaxMemories),
            logic.WithMinConfidence(m.config.MinConfidence),
        )

        // 2. 注入到 System Prompt
        if len(memories) > 0 {
            msgs = m.injectMemories(msgs, memories)
        }

        // 3. 执行原始调用
        return next(ctx, msgs, cfg)
    }
}

// handleControlEvent 处理 Control 事件(用户交互)
func (m *LogicMemoryMiddleware) handleControlEvent(event any) {
    // 转换为通用 Event
    genericEvent := m.convertToGenericEvent(event)

    // 异步处理(不阻塞主流程)
    if m.config.AsyncCapture {
        go m.processEventAsync(genericEvent)
    } else {
        m.manager.ProcessEvent(context.Background(), genericEvent)
    }
}

二、与现有 Memory 系统的对比和集成

2.1 四种 Memory 对比

特性Text MemoryWorking MemorySemantic MemoryLogic Memory (NEW)
用途长期知识存储临时状态管理语义检索用户偏好和行为模式
格式Markdown 文件JSON Schema向量 + Metadata结构化对象
检索文件路径/GrepKey-Value向量相似度类型/作用域/置信度
作用域NamespaceThread/ResourceNamespaceSession/User/Global
可读性高(人类可编辑)中(JSON)低(向量)高(Description 字段)
典型场景agent.md, 文档对话上下文RAG, 素材检索风格偏好、修改习惯

2.2 集成策略

Logic Memory 与现有 Memory 的协作

  1. 与 Text Memory 协作
    • Logic Memory 自动生成的高置信度模式可写入 /memory/patterns.md
    • 用户可编辑 Text Memory 来修正 Logic Memory
  2. 与 Semantic Memory 协作
    • Logic Memory 的 Description 字段可索引到 Semantic Memory
    • 支持语义检索("找到关于写作风格的 Memory")
  3. 与 Working Memory 协作
    • Session 级别的 Logic Memory 可转换为 Working Memory
    • Working Memory 的变化可触发 Logic Memory 更新

示例

// 在 Logic Memory Manager 中集成现有 Memory
type LogicMemoryManager struct {
    // 现有 Memory 系统
    textMemory     *memory.Manager
    semanticMemory *memory.SemanticMemory
    workingMemory  *memory.WorkingMemoryManager

    // Logic Memory 专用
    logicStore     LogicMemoryStore
    matchers       []PatternMatcher
}

// 自动同步到 Text Memory
func (m *LogicMemoryManager) RecordMemory(ctx context.Context, mem *LogicMemory) error {
    // 1. 存储到 Logic Store
    err := m.logicStore.Save(ctx, mem)

    // 2. 如果置信度高,同步到 Text Memory
    if mem.Provenance.Confidence > 0.85 {
        markdown := m.formatAsMarkdown(mem)
        m.textMemory.AppendNote(ctx, "/memory/patterns.md", mem.Key, markdown)
    }

    // 3. 索引到 Semantic Memory
    if mem.Description != "" {
        m.semanticMemory.Index(ctx, mem.ID, mem.Description, mem.Metadata())
    }

    return err
}

三、实施计划(3-4 周)

Week 1: 核心框架(Aster SDK 层)

Day 1-2: 数据模型和存储接口

新建文件

  • pkg/memory/logic/types.go - 核心数据结构
  • pkg/memory/logic/store.go - 存储接口定义
  • pkg/memory/logic/store_postgres.go - PostgreSQL 实现
  • pkg/memory/logic/store_inmemory.go - 内存实现(测试用)

数据库表设计

-- Aster SDK 通用表(应用层可扩展)
CREATE TABLE logic_memories (
    id VARCHAR(64) PRIMARY KEY,
    namespace VARCHAR(255) NOT NULL,  -- user:123, team:456, global
    scope VARCHAR(20) NOT NULL,       -- session/user/global

    type VARCHAR(100) NOT NULL,
    category VARCHAR(100),
    key VARCHAR(255) NOT NULL,
    value JSONB NOT NULL,
    description TEXT,

    -- Provenance (复用现有结构)
    source_type VARCHAR(50),
    confidence DECIMAL(3,2),
    sources JSONB,

    access_count INT DEFAULT 0,
    last_accessed TIMESTAMP,

    metadata JSONB,
    created_at TIMESTAMP NOT NULL,
    updated_at TIMESTAMP NOT NULL,

    UNIQUE INDEX idx_namespace_key (namespace, key),
    INDEX idx_namespace_type (namespace, type),
    INDEX idx_scope (scope),
    INDEX idx_confidence (confidence)
);

验收标准

  • LogicMemory 数据结构定义完整
  • LogicMemoryStore 接口定义清晰
  • PostgreSQL 实现单元测试通过
  • InMemory 实现可用于测试

Day 3-4: PatternMatcher 和 Manager

新建文件

  • pkg/memory/logic/matcher.go - PatternMatcher 接口
  • pkg/memory/logic/manager.go - LogicMemoryManager
  • pkg/memory/logic/event.go - Event 通用结构

核心逻辑

// manager.go - 核心管理器
func (m *LogicMemoryManager) ProcessEvent(ctx context.Context, event Event) error {
    // 1. 遍历所有 Matcher
    var allMemories []*LogicMemory
    for _, matcher := range m.matchers {
        if contains(matcher.SupportedEventTypes(), event.Type) {
            memories, err := matcher.MatchEvent(ctx, event)
            if err != nil {
                log.Warnf("Matcher failed: %v", err)
                continue
            }
            allMemories = append(allMemories, memories...)
        }
    }

    // 2. 保存或更新 Memory
    for _, mem := range allMemories {
        existing, err := m.store.Get(ctx, mem.Namespace, mem.Key)
        if err == nil && existing != nil {
            // 更新已有 Memory(提升置信度、累积证据)
            m.mergeMemory(existing, mem)
            m.store.Save(ctx, existing)
        } else {
            // 创建新 Memory
            m.store.Save(ctx, mem)
        }
    }

    return nil
}

// mergeMemory 合并新旧 Memory(提升置信度)
func (m *LogicMemoryManager) mergeMemory(existing, new *LogicMemory) {
    // 增加访问计数
    existing.AccessCount++

    // 提升置信度(最多提升 10%)
    boost := 0.05
    existing.Provenance.Confidence = min(existing.Provenance.Confidence + boost, 1.0)

    // 合并 Value(应用层自定义逻辑)
    // ...

    existing.UpdatedAt = time.Now()
}

验收标准

  • PatternMatcher 接口设计合理
  • LogicMemoryManager 核心逻辑完整
  • 支持多 Matcher 并行识别
  • Memory 合并逻辑测试通过

Day 5: Middleware 集成

新建文件

  • pkg/middleware/logic_memory.go - LogicMemoryMiddleware
  • pkg/middleware/logic_memory_test.go - 单元测试

集成点

// 1. 订阅 EventBus
func (m *LogicMemoryMiddleware) OnAgentStart(ctx context.Context, agentID string) error {
    // 订阅所有通道(根据配置)
    if contains(m.config.CaptureChannels, types.ChannelControl) {
        m.eventBus.OnControl("*", m.handleControlEvent)
    }
    if contains(m.config.CaptureChannels, types.ChannelMonitor) {
        m.eventBus.OnMonitor("*", m.handleMonitorEvent)
    }
    return nil
}

// 2. 注入 Memory 到 Prompt
func (m *LogicMemoryMiddleware) injectMemories(msgs []types.Message, memories []*logic.LogicMemory) []types.Message {
    if len(memories) == 0 {
        return msgs
    }

    // 构建 Memory 注入文本
    var builder strings.Builder
    builder.WriteString("\n\n## User Preferences and Memory\n\n")
    builder.WriteString("Based on past interactions, I've learned:\n\n")

    for i, mem := range memories {
        builder.WriteString(fmt.Sprintf(
            "%d. **%s** (%s): %s (Confidence: %.0f%%)\n",
            i+1, mem.Type, mem.Key, mem.Description, mem.Provenance.Confidence*100,
        ))
    }

    builder.WriteString("\nPlease apply these preferences naturally in your response.\n")

    // 注入到第一个 system message
    for i, msg := range msgs {
        if msg.Role == "system" {
            msgs[i].Content += builder.String()
            break
        }
    }

    return msgs
}

验收标准

  • Middleware 可注册到 Agent
  • EventBus 订阅成功
  • Memory 正确注入到 Prompt
  • 性能测试:开销 < 5%

Week 2: 高级功能(Aster SDK 层)

Day 6-7: Consolidation 和 Pruning

新建文件

  • pkg/memory/logic/consolidation.go - Memory 合并
  • pkg/memory/logic/pruning.go - Memory 清理

Consolidation(复用现有 ConsolidationEngine)

// consolidation.go

// ConsolidateMemories 合并冗余 Memory
func (m *LogicMemoryManager) ConsolidateMemories(ctx context.Context, namespace string) error {
    // 1. 获取所有 Memory
    memories, _ := m.store.List(ctx, namespace)

    // 2. 按类型分组
    grouped := m.groupByType(memories)

    // 3. 对每组执行合并
    for memType, group := range grouped {
        if len(group) < 2 {
            continue
        }

        // 使用现有 ConsolidationEngine(基于相似度)
        merged := m.consolidation.Consolidate(ctx, group)
        for _, mem := range merged {
            m.store.Save(ctx, mem)
        }

        // 删除被合并的 Memory
        for _, oldMem := range group {
            if !contains(merged, oldMem) {
                m.store.Delete(ctx, namespace, oldMem.Key)
            }
        }
    }

    return nil
}

Pruning(清理低价值 Memory)

// pruning.go

// PruneCriteria 清理条件
type PruneCriteria struct {
    MinConfidence    float64       // 最低置信度
    MaxAge           time.Duration // 最大年龄
    MinAccessCount   int           // 最少访问次数
    SinceLastAccess  time.Duration // 最后访问时间
}

// PruneMemories 清理低价值 Memory
func (m *LogicMemoryManager) PruneMemories(ctx context.Context, criteria PruneCriteria) (int, error) {
    // 1. 查询符合条件的 Memory
    allMemories, _ := m.store.List(ctx, "")

    // 2. 过滤低价值 Memory
    var toDelete []string
    for _, mem := range allMemories {
        if m.shouldPrune(mem, criteria) {
            toDelete = append(toDelete, mem.Key)
        }
    }

    // 3. 批量删除
    for _, key := range toDelete {
        m.store.Delete(ctx, mem.Namespace, key)
    }

    return len(toDelete), nil
}

// shouldPrune 判断是否应该清理
func (m *LogicMemoryManager) shouldPrune(mem *LogicMemory, criteria PruneCriteria) bool {
    // 置信度过低
    if mem.Provenance.Confidence < criteria.MinConfidence {
        return true
    }

    // 太久未访问
    if time.Since(mem.LastAccessed) > criteria.SinceLastAccess {
        return true
    }

    // 访问次数过少且年龄过大
    if mem.AccessCount < criteria.MinAccessCount && time.Since(mem.CreatedAt) > criteria.MaxAge {
        return true
    }

    return false
}

验收标准

  • Consolidation 合并相似 Memory
  • Pruning 清理低价值 Memory
  • 定时任务可配置(cron)
  • 日志记录合并和清理统计

Day 8-9: 监控和工具

新建文件

  • pkg/memory/logic/metrics.go - Prometheus 指标
  • pkg/tools/logic_memory_tool.go - Logic Memory 工具

Prometheus 监控

// metrics.go
var (
    memoryTotal = promauto.NewGaugeVec(
        prometheus.GaugeOpts{
            Name: "logic_memory_total",
            Help: "Total number of logic memories",
        },
        []string{"namespace", "type", "scope"},
    )

    memoryProcessDuration = promauto.NewHistogramVec(
        prometheus.HistogramOpts{
            Name:    "logic_memory_process_duration_seconds",
            Help:    "Time to process event and create memory",
            Buckets: prometheus.DefBuckets,
        },
        []string{"event_type"},
    )

    memoryRetrieveDuration = promauto.NewHistogram(
        prometheus.HistogramOpts{
            Name:    "logic_memory_retrieve_duration_seconds",
            Help:    "Time to retrieve memories",
            Buckets: prometheus.DefBuckets,
        },
    )
)

Logic Memory 工具(供 Agent 使用)

// pkg/tools/logic_memory_tool.go

// LogicMemoryTool 允许 Agent 主动查询和更新 Memory
type LogicMemoryTool struct {
    manager *logic.LogicMemoryManager
}

func (t *LogicMemoryTool) Definition() types.ToolDefinition {
    return types.ToolDefinition{
        Name: "logic_memory",
        Description: "Query and update logic memories (user preferences, behavior patterns)",
        InputSchema: jsonschema.Object{
            Properties: map[string]jsonschema.Schema{
                "action": {Type: "string", Enum: []string{"list", "get", "update"}},
                "type": {Type: "string"},
                "key": {Type: "string"},
                "value": {Type: "object"},
            },
            Required: []string{"action"},
        },
    }
}

func (t *LogicMemoryTool) Execute(ctx context.Context, input map[string]any) (string, error) {
    action := input["action"].(string)
    namespace := getNamespaceFromContext(ctx)

    switch action {
    case "list":
        memories, _ := t.manager.RetrieveMemories(ctx, namespace)
        return formatMemoriesAsMarkdown(memories), nil
    case "get":
        key := input["key"].(string)
        mem, _ := t.manager.store.Get(ctx, namespace, key)
        return formatMemoryAsMarkdown(mem), nil
    case "update":
        // Agent 主动更新 Memory
        // ...
    }

    return "", nil
}

验收标准

  • Prometheus 指标完整
  • Grafana Dashboard 模板
  • logic_memory 工具可用
  • 工具测试通过

Day 10: 文档和示例

新建文件

  • docs/memory/LOGIC_MEMORY.md - 完整文档
  • examples/logic_memory/ - 示例代码

文档结构

# Logic Memory Framework

## Overview
介绍 Logic Memory 的设计目标、架构、核心概念

## Quick Start
5 分钟快速开始

## Core Concepts
- Memory Types and Scopes
- PatternMatcher
- Consolidation and Pruning

## API Reference
完整 API 文档

## Integration Guide
如何在应用中集成 Logic Memory

## Best Practices
最佳实践和常见模式

## FAQ
常见问题解答

示例代码

// examples/logic_memory/basic/main.go

func main() {
    // 1. 创建 Logic Memory Store
    store := logic.NewPostgreSQLStore(db)

    // 2. 实现 PatternMatcher(应用层自定义)
    matcher := &MyPatternMatcher{}

    // 3. 创建 LogicMemoryManager
    manager := logic.NewManager(&logic.ManagerConfig{
        Store:    store,
        Matchers: []logic.PatternMatcher{matcher},
    })

    // 4. 配置 Middleware
    middleware := middleware.NewLogicMemoryMiddleware(&middleware.LogicMemoryConfig{
        Manager:          manager,
        EnableCapture:    true,
        EnableInjection:  true,
        MaxMemories:      5,
        MinConfidence:    0.6,
    })

    // 5. 注册到 Agent
    deps.MiddlewareStack.Add(middleware)

    // 完成!Logic Memory 自动工作
}

验收标准

  • 文档完整且准确
  • 示例代码可运行
  • API 文档清晰
  • 架构图和流程图完整

Week 3: YunJin 集成示例(应用层)

Day 11-13: YunJin PatternMatcher 实现

新建文件(在 YunJin 项目中):

  • internal/memory/pattern_matcher.go - YunJin 的 PatternMatcher
  • internal/memory/memory_types.go - YunJin 定义的 Memory 类型

YunJin 自定义 Memory 类型

// internal/memory/memory_types.go

const (
    TypeWritingTone      = "writing_tone"      // 写作语气偏好
    TypeMaterialSource   = "material_source"   // 素材来源偏好
    TypeStructure        = "structure"         // 结构偏好
    TypeWordChoice       = "word_choice"       // 用词偏好
    TypeTopicSuitability = "topic_suitability" // 主题适配性
)

// WritingTonePreference 写作语气偏好
type WritingTonePreference struct {
    PreferredTone string   // "formal", "casual", "humorous"
    AvoidedPhrases []string // 避免的词汇
    Examples       []RevisionExample
}

// RevisionExample 修改示例
type RevisionExample struct {
    From string
    To   string
    Reason string
}

YunJin PatternMatcher 实现

// internal/memory/pattern_matcher.go

type YunJinPatternMatcher struct {
    // 可选:使用 LLM 辅助识别
    provider provider.Provider
}

func (m *YunJinPatternMatcher) SupportedEventTypes() []string {
    return []string{
        "user_revision",     // 用户修改内容
        "user_feedback",     // 用户评价
        "topic_selection",   // 主题选择
        "material_rejection",// 素材拒绝
    }
}

func (m *YunJinPatternMatcher) MatchEvent(ctx context.Context, event logic.Event) ([]*logic.LogicMemory, error) {
    switch event.Type {
    case "user_revision":
        return m.matchRevisionPattern(ctx, event)
    case "user_feedback":
        return m.matchFeedbackPattern(ctx, event)
    // ...
    }
    return nil, nil
}

// matchRevisionPattern 识别用户修改模式
func (m *YunJinPatternMatcher) matchRevisionPattern(ctx context.Context, event logic.Event) ([]*logic.LogicMemory, error) {
    original := event.Data["original"].(string)
    revised := event.Data["revised"].(string)

    var memories []*logic.LogicMemory

    // 规则 1: 删除书面语
    if m.containsFormalWords(original) && !m.containsFormalWords(revised) {
        mem := &logic.LogicMemory{
            Namespace:   event.Source,
            Scope:       logic.ScopeUser,
            Type:        TypeWritingTone,
            Key:         "casual_tone_preference",
            Value: WritingTonePreference{
                PreferredTone: "casual",
                AvoidedPhrases: m.extractRemovedFormalWords(original, revised),
                Examples: []RevisionExample{{From: original, To: revised}},
            },
            Description: "用户偏好口语化表达,避免使用书面语",
            Provenance: &memory.MemoryProvenance{
                SourceType: memory.SourceUserInput,
                Confidence: 0.70,
            },
        }
        memories = append(memories, mem)
    }

    // 规则 2: 增加 emoji
    // 规则 3: 缩短段落
    // ...

    return memories, nil
}

// 可选:使用 LLM 辅助识别(更准确但更慢)
func (m *YunJinPatternMatcher) matchWithLLM(ctx context.Context, original, revised string) (*logic.LogicMemory, error) {
    prompt := fmt.Sprintf(`
分析用户的修改行为,识别写作偏好。

原文:%s
修改后:%s

请用 JSON 返回:
{
  "type": "...",
  "key": "...",
  "description": "...",
  "confidence": 0.80
}
`, original, revised)

    response, _ := m.provider.CallModel(ctx, []types.Message{{Role: "user", Content: prompt}}, nil)
    // 解析 JSON 并构建 LogicMemory
    // ...
}

验收标准

  • YunJinPatternMatcher 实现完整
  • 5 种 Memory 类型定义清晰
  • 单元测试覆盖所有规则
  • 可选的 LLM 辅助识别

Day 14-15: YunJin 集成和测试

修改文件(在 YunJin 项目中):

  • internal/agent/agent_manager.go - 集成 Logic Memory
  • cmd/server/main.go - 初始化配置

集成代码

// internal/agent/agent_manager.go

func NewAgentManager(config *Config) *AgentManager {
    // 1. 创建 Logic Memory Store
    logicStore := logic.NewPostgreSQLStore(config.DB)

    // 2. 创建 YunJin PatternMatcher
    matcher := memory.NewYunJinPatternMatcher(config.Provider)

    // 3. 创建 LogicMemoryManager
    logicManager := logic.NewManager(&logic.ManagerConfig{
        Store:    logicStore,
        Matchers: []logic.PatternMatcher{matcher},
    })

    // 4. 创建 LogicMemoryMiddleware
    logicMiddleware := middleware.NewLogicMemoryMiddleware(&middleware.LogicMemoryConfig{
        Manager:         logicManager,
        EventBus:        config.EventBus,
        EnableCapture:   true,
        CaptureChannels: []types.AgentChannel{types.ChannelControl, types.ChannelMonitor},
        EnableInjection: true,
        MaxMemories:     5,
        MinConfidence:   0.6,
        AsyncCapture:    true,
        CacheTTL:        time.Hour,
    })

    // 5. 注册到 Middleware Stack
    config.MiddlewareStack.Add(logicMiddleware)

    return &AgentManager{
        // ...
        logicManager: logicManager,
    }
}

// 手动触发事件(可选)
func (m *AgentManager) HandleUserRevision(ctx context.Context, sessionID uint, original, revised string) {
    event := logic.Event{
        Type:   "user_revision",
        Source: fmt.Sprintf("user:%d", m.getUserID(sessionID)),
        Data: map[string]any{
            "session_id": sessionID,
            "original":   original,
            "revised":    revised,
        },
        Timestamp: time.Now(),
    }

    m.logicManager.ProcessEvent(ctx, event)
}

端到端测试

// test/logic_memory_test.go

func TestLogicMemoryE2E(t *testing.T) {
    // 1. 用户第一次创作(生成正式表达)
    session := createSession(userID, "技术文章")
    content := generateContent(session, "介绍 Go 语言特性")
    assert.Contains(t, content, "然而") // 正式语气

    // 2. 用户修改为口语化
    revisedContent := strings.ReplaceAll(content, "然而", "不过")
    handleUserRevision(session.ID, content, revisedContent)

    // 3. 等待 Memory 处理
    time.Sleep(100 * time.Millisecond)

    // 4. 验证 Memory 创建
    memories := getLogicMemories(userID)
    assert.Equal(t, 1, len(memories))
    assert.Equal(t, "casual_tone_preference", memories[0].Key)
    assert.Contains(t, memories[0].Description, "口语化")

    // 5. 用户第二次创作(应该应用 Memory)
    session2 := createSession(userID, "技术文章")
    content2 := generateContent(session2, "介绍 Rust 语言特性")
    assert.NotContains(t, content2, "然而") // 已学习,不再使用正式语气
    assert.Contains(t, content2, "不过")    // 使用口语化表达

    // 6. 验证 Memory 置信度提升
    updatedMemories := getLogicMemories(userID)
    assert.GreaterOrEqual(t, updatedMemories[0].Provenance.Confidence, 0.75)
}

验收标准

  • YunJin 完整集成 Logic Memory
  • 端到端测试通过
  • 性能测试:对主流程影响 < 3%
  • 用户体验测试:Memory 注入准确

Week 4: 文档和发布

Day 16-18: 完善文档和示例

Aster SDK 文档

  • docs/memory/LOGIC_MEMORY.md - 完整文档
  • docs/memory/ARCHITECTURE.md - 架构设计
  • docs/memory/API.md - API 参考
  • docs/memory/INTEGRATION_GUIDE.md - 集成指南
  • examples/logic_memory/ - 多个示例

YunJin 文档

  • docs/LOGIC_MEMORY_INTEGRATION.md - 集成说明
  • docs/PATTERN_MATCHER.md - PatternMatcher 开发指南

验收标准

  • 文档完整且准确
  • 示例代码可运行
  • 架构图清晰
  • API 文档完整

Day 19-20: 性能优化和发布准备

性能优化

  • Memory 查询缓存(Redis)
  • 批量事件处理(减少 goroutine)
  • 数据库索引优化
  • Prometheus 监控完善

发布准备

  • 版本号:v0.1.0-beta
  • CHANGELOG.md
  • 迁移指南(对现有 Aster 用户)
  • 安全审计(PII 检查)

四、核心设计决策和权衡

4.1 为什么不在 Session 层实现?

决策:在 Memory 层实现,而非 Session 层

理由

  • Session 是临时性的,Logic Memory 需要跨 Session 持久化
  • Memory 层已有完善的 Provenance、Consolidation 机制,可复用
  • 符合 Aster 的四层 Memory 架构(Text/Working/Semantic/Logic)

4.2 为什么支持多 PatternMatcher?

决策:支持多个 PatternMatcher 并行工作

理由

  • 应用层可能需要多种识别策略(规则 + LLM + 统计)
  • 不同 Memory 类型可能需要不同的 Matcher
  • 提高框架的灵活性和可扩展性

4.3 为什么异步捕获?

决策:默认异步捕获,可配置同步模式

理由

  • 不阻塞主流程(用户体验优先)
  • 事件处理可能耗时(LLM 调用、数据库写入)
  • 大多数场景下,Memory 不需要实时生效

权衡

  • 异步可能丢失部分事件(通过 buffered channel 缓解)
  • 调试难度增加(通过日志和监控缓解)

4.4 为什么不自动启用?

决策:Logic Memory 需要应用层显式配置和启用

理由

  • 需要应用层提供 PatternMatcher(无法通用)
  • 需要应用层定义 Memory 类型(业务相关)
  • 避免对不需要 Logic Memory 的应用造成性能开销

五、与演讲内容的对应

5.1 Memory OS 系统化管理 ✅

演讲要求

"Memory OS 是一个严谨的系统,你要什么时候写入,具体上来了一个 memory,那这个 memory 你是要写入短期、写入中期、写入长期。一旦它写入了短期之后,它多久变成长期,多久会变成中期。"

Aster 实现

  • 三种作用域:Session(短期)、User(中期)、Global(长期)
  • 自动转换:基于置信度、访问频率自动升级作用域
  • Consolidation:定期合并相似 Memory,清理冗余
  • Pruning:自动清理低价值 Memory

5.2 Memory RL(暂不实现)❌

演讲要求

"专门用 RL 模型去做短期记忆的这种 update,然后他们的一些奖励就可以是,你存进去的记忆是不是足够的精炼?"

Aster 方案

  • Phase 1(当前):基于规则 + 置信度的启发式方法
  • Phase 2(未来):LLM 驱动的 Pattern 识别
  • Phase 3(研究):RL-based Memory 管理

理由:RL 需要大量数据和训练,当前启发式方法已足够实用。

5.3 Logic Memory(执行轨迹)✅

演讲要求

"我过往执行了什么操作,然后他成功了;执行了什么操作,他失败了,然后失败了之后我去做 reflection,然后他又成功了,那我这时候这个 reflection 的东西作为我的一个 memory。"

Aster 实现

  • Event 驱动:自动捕获所有事件(成功/失败)
  • PatternMatcher:识别成功/失败模式
  • Provenance:追踪 Memory 来源和置信度
  • Consolidation:合并相关 Memory 形成经验

未来增强

  • Reflection Engine:专门的反思模块
  • Success Pattern Mining:从成功案例中提取模式
  • Failure Pattern Detection:识别失败模式并避免

5.4 Critical Learning ✅

演讲要求

"我在 code agent 的执行过程中,我有一些代码规范我让它去遵守,然后我在执行过程中我发现我需要补充一些代码规范,这种去补充的这部分其实就是一个 critical learning 的过程。"

Aster 实现

  • 用户修改捕获:自动捕获用户对生成内容的修改
  • Pattern 识别:从修改中提取规范(如"避免书面语")
  • Memory 累积:多次修改提升置信度,形成可靠的规范
  • 自动应用:后续生成自动遵守学到的规范

六、关键文件清单

Aster SDK 新增文件(框架层)

文件路径功能行数估计
pkg/memory/logic/types.go核心数据结构200
pkg/memory/logic/store.go存储接口150
pkg/memory/logic/store_postgres.goPostgreSQL 实现300
pkg/memory/logic/store_inmemory.go内存实现150
pkg/memory/logic/matcher.goPatternMatcher 接口100
pkg/memory/logic/manager.goLogicMemoryManager400
pkg/memory/logic/event.goEvent 结构100
pkg/memory/logic/consolidation.goMemory 合并250
pkg/memory/logic/pruning.goMemory 清理200
pkg/memory/logic/metrics.goPrometheus 指标100
pkg/middleware/logic_memory.goMiddleware350
pkg/tools/logic_memory_tool.goLogic Memory 工具200
测试文件
pkg/memory/logic/*_test.go单元测试800
test/integration/logic_memory_test.go集成测试300
文档
docs/memory/LOGIC_MEMORY.md完整文档-
docs/memory/ARCHITECTURE.md架构设计-
docs/memory/API.mdAPI 参考-
examples/logic_memory/示例代码500

总计:约 3,600 行代码 + 文档

YunJin 应用层文件(示例)

文件路径功能行数估计
internal/memory/pattern_matcher.goYunJin PatternMatcher400
internal/memory/memory_types.go自定义 Memory 类型150
internal/agent/agent_manager.go集成 Logic Memory+100
cmd/server/main.go初始化配置+50
test/logic_memory_test.go端到端测试300

总计:约 1,000 行代码


七、时间线和里程碑

日期里程碑交付物验收标准
Week 1核心框架
Day 1-2数据模型和存储types.go, store*.go单元测试通过
Day 3-4PatternMatcher 和 Managermatcher.go, manager.go核心逻辑完整
Day 5Middleware 集成logic_memory.go (middleware)Memory 注入成功
Week 2高级功能
Day 6-7Consolidation 和 Pruningconsolidation.go, pruning.go合并和清理测试通过
Day 8-9监控和工具metrics.go, logic_memory_tool.goPrometheus 指标完整
Day 10文档和示例docs/, examples/文档完整
Week 3YunJin 集成
Day 11-13PatternMatcher 实现pattern_matcher.go (YunJin)5 种规则实现
Day 14-15集成和测试修改 agent_manager.goE2E 测试通过
Week 4发布准备
Day 16-18完善文档完整文档和示例文档完整
Day 19-20性能优化和发布v0.1.0-beta性能达标

总计:20 个工作日(3-4 周)


八、成功指标

Aster SDK 层面

指标目标验证方式
通用性支持 3+ 应用场景YunJin + 2 个其他示例
性能主流程开销 < 5%性能基准测试
可扩展性支持自定义 PatternMatcher接口设计和文档
易用性10 行代码完成集成Quick Start 示例
测试覆盖率> 80%go test -cover

YunJin 应用层面

指标目标验证方式
Memory 捕获率> 80%每次用户修改都触发
Pattern 准确率> 70%人工评估 50 个样本
用户满意度> 4.0/5.0Beta 用户问卷
首次成功率提升60% → 85%A/B 测试

九、风险和缓解

风险 1:框架过于复杂 ⚠️

风险:应用层集成成本高

缓解

  • 提供 Quick Start(10 行代码)
  • 提供 3+ 完整示例
  • 提供默认 PatternMatcher(基于规则)

风险 2:性能影响主流程 ⚠️

风险:Memory 捕获和查询影响性能

缓解

  • 默认异步捕获
  • Redis 缓存 TopK Memory
  • 数据库索引优化
  • 可配置关闭 Logic Memory

风险 3:PatternMatcher 准确率低 ⚠️

风险:基于规则的识别不准确

缓解

  • 支持 LLM 辅助识别(可选)
  • 用户可编辑/删除 Memory
  • 置信度阈值过滤(MinConfidence)
  • 未来引入 RL 优化

风险 4:存储成本 ⚠️

风险:大量 Memory 导致存储成本高

缓解

  • 自动 Pruning(清理低价值 Memory)
  • 每用户限制 Memory 数量
  • 定期 Consolidation(合并相似 Memory)
  • 支持 Redis Store(低成本)

十、未来演进方向

Phase 2: LLM 驱动的 Pattern 识别(2-3 个月)

目标:提升 Pattern 识别准确率到 90%+

方案

  • 使用 LLM 分析事件,生成结构化 Pattern
  • 训练专门的 Pattern 识别模型
  • 支持多模态事件(文本 + 图像)

Phase 3: Reflection Engine(3-4 个月)

目标:实现自我反思和错误归因

方案

  • 专门的 ReflectionEngine 模块
  • 从失败事件中自动生成 Reflection
  • Reflection 作为高置信度 Logic Memory

Phase 4: SOP 自动生成(6 个月)

目标:从 Pattern 自动生成可执行的 SOP

方案

  • Pattern → Workflow DSL 转换
  • 统计最佳实践概率分布
  • 生成可复用的 Workflow 模板

Phase 5: Memory RL(12 个月)

目标:使用强化学习优化 Memory 管理

方案

  • RL 模型决策 Memory 写入/删除/合并
  • 奖励函数:信息保留率、检索准确率
  • 在线学习和策略更新

十一、总结

为什么这个设计合理?

  1. 通用性强:框架层提供机制,应用层定义策略
  2. 最小侵入:通过 Middleware 自动工作,无需手动调用
  3. 可扩展性:支持自定义 PatternMatcher、Storage Backend
  4. 生产就绪:完整的监控、测试、文档
  5. 与现有 Memory 系统协作:复用 Provenance、Consolidation

核心价值

"让 AI Agent 从经验中学习" - 这是传统 Memory 系统(仅存储知识)无法提供的能力。Logic Memory 让 Agent 能够:

  • 记住用户的偏好和习惯
  • 从成功和失败中学习
  • 自动改进行为策略
  • 实现真正的个性化

下一步行动

  1. 审阅计划:确认技术方案和时间线
  2. 🚀 启动 Week 1:实现核心框架(types, store, manager)
  3. 📝 定期同步:每周五同步进度和反馈
  4. 🎯 4 周目标:完成框架 + YunJin 集成,发布 v0.1.0-beta

计划制定时间:2025-12-04 预计完成时间:2025-12-30(4 周) 置信度:高(基于 Aster SDK 和 YunJin 的实际代码分析)