AI Agent 记忆系统深度解析：KVCache 命中、上下文压缩与相似检索实战

CONTEXT WINDOW (始终加载，~192K tokens)
├── System Prompts (~4-5K tokens)
├── Core Memory / MEMORY.md (~3K tokens)  ← 始终在上下文
└── Conversation + Tools (~185K+)

MEMORY STORES (按需检索)
├── Episodic   — 时间顺序事件日志（append-only）
├── Semantic   — 知识图谱（实体 + 关系）
├── Procedural — 学到的工作流和模式
└── Vault      — 用户固定，永不自动衰减

ENGINES
├── Trigger Engine    — 关键词检测 + LLM 路由
├── Reflection Engine — 反思 consolidation
└── Retrieval Engine  — 混合检索（本地 + 向量 + 文本）

workspace/
├── MEMORY.md                    # Core memory (~3K tokens)
├── IDENTITY.md                  # 事实 + 自我认知
├── SOUL.md                      # 价值观、原则、承诺
├── memory/
│   ├── episodes/                # 每日日志：YYYY-MM-DD.md
│   ├── graph/                   # 知识图谱
│   │   ├── index.md             # 实体注册表 + 边
│   │   ├── entities/            # 每个实体一个文件
│   │   └── relations.md         # 边类型定义
│   ├── procedures/              # 学到的工作流
│   ├── vault/                   # 固定记忆（无衰减）
│   └── meta/
│       ├── decay-scores.json    # 相关性 + token 经济追踪
│       ├── reflection-log.md    # 反思摘要（上下文加载）
│       └── audit.log            # 审计日志

L1 Cache (Hot) - 始终在 GPU 显存
├── System Prompts
├── Core Memory (MEMORY.md)
└── 最近 10 轮对话

L2 Cache (Warm) - 系统内存，按需加载
├── 知识图谱热点实体
├── 最近 24 小时事件
└── 高频工作流

L3 Cache (Cold) - 磁盘存储，向量检索
├── 历史对话全文
├── 知识图谱全量
└── 归档记忆

// 基于 OpenClaw memory-autodb 的实现
interface CacheHitRule {
  priority: number;        // 优先级（1-10）
  matchType: 'exact' | 'semantic' | 'temporal';
  threshold: number;       // 命中阈值
  ttl?: number;           // 生存时间（秒）
}

class KVCacheManager {
  private l1Cache = new Map<string, CacheEntry>();
  private l2Cache = new LRUCache({ max: 1000 });
  private l3DB: MemoryDB;  // LanceDB

  // 命中规则配置
  private hitRules: CacheHitRule[] = [
    {
      priority: 10,
      matchType: 'exact',
      threshold: 1.0,
      ttl: 3600  // 1 小时
    },
    {
      priority: 8,
      matchType: 'semantic',
      threshold: 0.85,
      ttl: 86400  // 24 小时
    },
    {
      priority: 5,
      matchType: 'temporal',
      threshold: 0.7,
      ttl: 604800  // 7 天
    }
  ];

  async get(query: string): Promise<CacheEntry | null> {
    // 1. 尝试 L1 Cache（精确匹配）
    const l1Hit = this.l1Cache.get(query);
    if (l1Hit && ![记忆检索流程图]his.isExpired(l1Hit)) {
      this.hitStats.l1Hits++;
      return l1Hit;
    }

    // 2. 尝试 L2 Cache（语义匹配）
    const l2Hit = await this.l2Cache.get(query);
    if (l2Hit && l2Hit.score >= 0.85) {
      this.hitStats.l2Hits++;
      // 提升到 L1
      this.promoteToL1(l2Hit);
      return l2Hit.entry;
    }

    // 3. 尝试 L3 DB（向量检索）
    const queryVector = await this.embeddings.embed(query);
    const l3Results = await this.l3DB.search(queryVector, 5, 0.7);

    if (l3Results.length > 0) {
      this.hitStats.l3Hits++;
      // 提升到 L2
      const top = l3Results[0];
      this.l2Cache.set(query, {
        entry: top.entry,
        score: top.score,
        timestamp: Date.now()
      });
      return top.entry;
    }

    this.hitStats.misses++;
    return null;
  }

  private isExpired(entry: CacheEntry): boolean {
    const rule = this.hitRules.find(r => r.priority === entry.priority);
    if (!rule?.ttl) return false;

    return Date.now() - entry.timestamp > rule.ttl;
  }

  private promoteToL1(entry: CacheEntry): void {
    // L1 缓存管理策略
    if (this.l1Cache.size >= 100) {
      // 移除最旧的条目
      const oldest = Array.from(this.l1Cache.entries())
        .sort((a, b) => a[1].timestamp - b[1].timestamp)[0];
      this.l1Cache.delete(oldest[0]);
    }
    this.l1Cache.set(entry.id, entry);
  }
}

原始对话 (100%)
    ↓ [摘要压缩]
对话摘要 (30%)
    ↓ [实体提取]
关键实体 (10%)
    ↓ [决策提取]
核心决策 (3%)
    ↓ [用户偏好]
用户画像 (1%)

class ContextCompressor {
  private llm: LLMClient;

  // 多层压缩策略
  async compress(
    conversation: string[],
    targetRatio: number
  ): Promise<string> {
    const originalLength = conversation.join(' ').length;

    if (targetRatio >= 0.5) {
      // 轻度压缩：删除冗余
      return this.lightCompression(conversation);
    } else if (targetRatio >= 0.2) {
      // 中度压缩：摘要
      return await this.summaryCompression(conversation);
    } else {
      // 重度压缩：提取关键点
      return await this.heavyCompression(conversation);
    }
  }

  private async summaryCompression(
    conversation: string[]
  ): Promise<string> {
    const prompt = `请总结以下对话的关键信息，保留：
1. 用户明确表达的需求和偏好
2. 重要的决策和结论
3. 待执行的任务和行动项

对话内容：
${conversation.join('\n')}

总结（300 字以内）：`;

    const summary = await this.llm.generate(prompt);
    return summary;
  }

  private async heavyCompression(
    conversation: string[]
  ): Promise<string> {
    // 提取结构化信息
    const entities = await this.extractEntities(conversation);
    const decisions = await this.extractDecisions(conversation);
    const preferences = await this.extractPreferences(conversation);

    return JSON.stringify({
      entities,
      decisions,
      preferences
    }, null, 2);
  }

  private async extractEntities(
    conversation: string[]
  ): Promise<Entity[]> {
    // 使用 NER 模型提取实体
    // 实现略...
    return [];
  }
}

class AdaptiveCompressor {
  private contextUsage: number = 0;

  async getContextWithCompression(
    conversation: string[],
    maxTokens: number
  ): Promise<string> {
    const currentTokens = this.countTokens(conversation);
    this.contextUsage = currentTokens / maxTokens;

    if (this.contextUsage < 0.6) {
      // 使用率低，不压缩
      return conversation.join('\n');
    } else if (this.contextUsage < 0.8) {
      // 中等使用率，轻度压缩
      return await this.compressor.compress(conversation, 0.5);
    } else if (this.contextUsage < 0.9) {
      // 高使用率，中度压缩
      return await this.compressor.compress(conversation, 0.3);
    } else {
      // 临界状态，重度压缩
      return await this.compressor.compress(conversation, 0.1);
    }
  }
}

class LocalCacheRetriever {
  private cache = new Map<string, MemoryEntry>();
  private index = new Map<string, string[]>(); // 关键词 → 记忆 ID

  // 构建倒排索引
  buildIndex(entries: MemoryEntry[]): void {
    for (const entry of entries) {
      const keywords = this.extractKeywords(entry.text);
      for (const keyword of keywords) {
        if (![记忆检索流程图]his.index.has(keyword)) {
          this.index.set(keyword, []);
        }
        this.index.get(keyword)!.push(entry.id);
      }
      this.cache.set(entry.id, entry);
    }
  }

  // 检索
  search(query: string, limit: number = 10): MemoryEntry[] {
    const keywords = this.extractKeywords(query);
    const candidates = new Map<string, number>();

    // 计算关键词匹配分数
    for (const keyword of keywords) {
      const ids = this.index.get(keyword) || [];
      for (const id of ids) {
        candidates.set(id, (candidates.get(id) || 0) + 1);
      }
    }

    // 排序并返回
    return Array.from(candidates.entries())
      .sort((a, b) => b[1] - a[1])
      .slice(0, limit)
      .map(([id]) => this.cache.get(id)!);
  }

  private extractKeywords(text: string): string[] {
    // 简单的中文分词（实际应该用更好的分词器）
    return text
      .toLowerCase()
      .split(/[\s,，.。]+/)
      .filter(w => w.length > 1);
  }
}

// LanceDB 向量检索
class VectorRetriever {
  private db: MemoryDB;
  private embeddings: Embeddings;

  async search(
    query: string,
    limit: number = 5,
    minScore: number = 0.5
  ): Promise<MemorySearchResult[]> {
    // 1. 生成查询向量
    const queryVector = await this.embeddings.embed(query);

    // 2. 向量检索
    const results = await this.db.search(queryVector, limit);

    // 3. 距离转相似度分数
    const mapped = results.map((row) => {
      const distance = row._distance ?? 0;
      // L2 距离转相似度：sim = 1 / (1 + d)
      const score = 1 / (1 + distance);
      return {
        entry: row.entry,
        score
      };
    });

    // 4. 过滤低分结果
    return mapped.filter((r) => r.score >= minScore);
  }

  // 混合检索：向量 + 关键词
  async hybridSearch(
    query: string,
    keywords: string[],
    limit: number = 10
  ): Promise<MemorySearchResult[]> {
    // 1. 向量检索
    const vectorResults = await this.search(query, limit * 2);

    // 2. 关键词检索
    const keywordResults = this.localRetriever.search(query, limit * 2);

    // 3. 融合结果（Reciprocal Rank Fusion）
    const fused = this.reciprocalRankFusion(
      vectorResults,
      keywordResults,
      limit
    );

    return fused;
  }

  private reciprocalRankFusion(
    vectorResults: MemorySearchResult[],
    keywordResults: MemoryEntry[],
    limit: number
  ): MemorySearchResult[] {
    const scores = new Map<string, number>();
    const k = 60; // RFF 常数

    // 向量检索分数
    vectorResults.forEach((r, i) => {
      scores.set(r.entry.id, (scores.get(r.entry.id) || 0) + 1 / (k + i));
    });

    // 关键词检索分数
    keywordResults.forEach((r, i) => {
      scores.set(r.id, (scores.get(r.id) || 0) + 1 / (k + i));
    });

    // 排序
    return Array.from(scores.entries())
      .sort((a, b) => b[1] - a[1])
      .slice(0, limit)
      .map(([id]) => {
        const vectorResult = vectorResults.find(r => r.entry.id === id);
        return vectorResult!;
      });
  }
}

import Database from 'better-sqlite3';

class TextRetriever {
  private db: Database;

  constructor(dbPath: string) {
    this.db = new Database(dbPath);

    // 创建 FTS5 虚拟表
    this.db.exec(`
      CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
        text,
        category,
        content='memories',
        content_rowid='id'
      );
    `);
  }

  search(query: string, limit: number = 10): MemoryEntry[] {
    // FTS5 全文检索
    const stmt = this.db.prepare(`
      SELECT m.*, bm25(memories_fts) as relevance
      FROM memories_fts
      JOIN memories m ON memories_fts.rowid = m.id
      WHERE memories_fts MATCH ?
      ORDER BY relevance
      LIMIT ?
    `);

    return stmt.all(query, limit) as MemoryEntry[];
  }

  // 高级检索：支持布尔运算
  advancedSearch(
    must: string[],    // 必须包含
    should: string[],  // 应该包含
    mustNot: string[]  // 不应包含
  ): MemoryEntry[] {
    const query = this.buildBooleanQuery(must, should, mustNot);
    return this.search(query);
  }

  private buildBooleanQuery(
    must: string[],
    should: string[],
    mustNot: string[]
  ): string {
    const parts: string[] = [];

    // 必须包含
    if (must.length > 0) {
      parts.push(must.map(w => `+${w}`).join(' '));
    }

    // 应该包含
    if (should.length > 0) {
      parts.push(should.join(' '));
    }

    // 不应包含
    if (mustNot.length > 0) {
      parts.push(mustNot.map(w => `-${w}`).join(' '));
    }

    return parts.join(' ');
  }
}

class HybridRetriever {
  private localCache: LocalCacheRetriever;
  private vectorDB: VectorRetriever;
  private textDB: TextRetriever;

  async search(
    query: string,
    options: SearchOptions
  ): Promise<SearchResult[]> {
    const results: SearchResult[] = [];

    // 1. 本地缓存（精确匹配）
    if (options.useCache) {
      const cacheResults = this.localCache.search(query);
      results.push(...cacheResults.map(r => ({
        source: 'local_cache' as const,
        entry: r,
        score: 1.0,
        latency: '<1ms'
      })));
    }

    // 2. 向量检索（语义匹配）
    if (options.useVector) {
      const vectorResults = await this.vectorDB.search(
        query,
        options.limit,
        options.minScore
      );
      results.push(...vectorResults.map(r => ({
        source: 'vector_db' as const,
        entry: r.entry,
        score: r.score,
        latency: '50-100ms'
      })));
    }

    // 3. 文本检索（关键词匹配）
    if (options.useText) {
      const textResults = this.textDB.search(query, options.limit);
      results.push(...textResults.map(r => ({
        source: 'text_db' as const,
        entry: r,
        score: this.calculateTextScore(r, query),
        latency: '10-20ms'
      })));
    }

    // 4. 结果融合和去重
    return this.fuseAndDeduplicate(results, options.limit);
  }

  private fuseAndDeduplicate(
    results: SearchResult[],
    limit: number
  ): SearchResult[] {
    // 使用 Reciprocal Rank Fusion
    const scores = new Map<string, number>();
    const entries = new Map<string, SearchResult>();

    results.forEach((r, i) => {
      const rank = i + 1;
      const score = 1 / (60 + rank);
      scores.set(r.entry.id, (scores.get(r.entry.id) || 0) + score);
      entries.set(r.entry.id, r);
    });

    return Array.from(scores.entries())
      .sort((a, b) => b[1] - a[1])
      .slice(0, limit)
      .map(([id]) => entries.get(id)!);
  }
}

// 基于时间模式预加载
async warmupCache(timeOfDay: string): Promise<void> {
  if (timeOfDay === 'morning') {
    // 早上加载日程相关记忆
    const memories = await this.search('日程 会议 安排');
    this.l2Cache.setMany(memories);
  }
}

// 一次性检索多个相关查询
async batchSearch(queries: string[]): Promise<Map<string, SearchResult[]>> {
  // 合并相似查询
  const grouped = this.groupSimilarQueries(queries);

  // 批量检索
  const results = await Promise.all(
    grouped.map(group => 
      this.search(group.queries.join(' '), group.options)
    )
  );

  return this.distributeResults(grouped, results);
}

// 非阻塞检索
async searchAsync(query: string): Promise<void> {
  // 立即返回缓存结果
  const cached = this.l1Cache.get(query);
  if (cached) {
    return this.respond(cached);
  }

  // 后台加载
  this.backgroundLoad(query).then(result => {
    this.pushUpdate(result);  // 推送更新
  });
}

class MemoryManager {
  private maxMemoryMB: number = 512;
  private currentMemoryMB: number = 0;

  async add(entry: MemoryEntry): Promise<void> {
    const size = this.estimateSize(entry);

    // 内存不足时触发 GC
    if (this.currentMemoryMB + size > this.maxMemoryMB) {
      await this.garbageCollect();
    }

    this.cache.set(entry.id, entry);
    this.currentMemoryMB += size;
  }

  private async garbageCollect(): Promise<void> {
    // 1. 移除过期条目
    const expired = Array.from(this.cache.entries())
      .filter(([_, e]) => this.isExpired(e));
    expired.forEach(([id]) => this.cache.delete(id));

    // 2. LRU 淘汰
    if (this.currentMemoryMB > this.maxMemoryMB * 0.8) {
      const lru = this.getLRUEntries(100);
      lru.forEach(([id]) => {
        this.cache.delete(id);
      });
    }
  }
}