agent-memory-system

Agent 记忆系统

概述

agent-memory-system 提供持久化记忆架构，使 AI Agent 能够跨会话记忆、从经验中学习并构建长期知识。

目的：通过持久化记忆实现真正的持续改进

模式：基于能力（4 种记忆类型，各自独立运行）

关键创新：多层记忆架构（情景、程序、语义、短期），使 Agent 能够随着时间推移学习和适应

核心原则：

1. 情景记忆 - 记住特定的过往事件和决策
2. 程序记忆 - 随着时间推移学习并提升技能
3. 语义记忆 - 构建事实和关系的知识图谱
4. 短期记忆 - 当前活跃的工作上下文

---

适用场景

在以下情况下使用 agent-memory-system：

• 构建能够从经验中学习的 Agent
• 在多个会话间保留上下文
• 实现个性化（记住用户偏好）
• 创建自适应系统（随时间改进）
• 长期运行的项目（记住几周前做出的决策）
• 跟踪技能提升情况（哪些有效，哪些无效）

---

前置条件

必需

• 文件系统访问权限（用于基于文件的记忆）
• JSON 支持（用于结构化记忆存储）

可选

• 用于情景记忆的向量数据库（Pinecone、Weaviate、Chroma）
• 用于语义记忆的图数据库（Neo4j）
• 用于快速短期记忆的 Redis

需要了解

• 记忆类型及各自的适用场景
• 权衡取舍（基于文件与基于数据库）

---

记忆类型

记忆类型 1：情景记忆

定义：记住特定的过往事件、决策及其结果

适用场景：需要回忆“上次尝试 X 时发生了什么？”

存储：向量数据库（相似度搜索）或带时间戳的 JSON 文件

结构：

{
  "episode_id": "ep_20250115_1530",
  "timestamp": "2025-01-15T15:30:00Z",
  "event_type": "implementation",
  "description": "Implemented user authentication with OAuth",
  "context": {
    "objective": "Add OAuth to existing password auth",
    "approach": "Expand-migrate-contract pattern",
    "decisions": [
      {
        "question": "JWT vs Sessions?",
        "choice": "JWT",
        "rationale": "Stateless, scales better"
      }
    ],
    "outcomes": {
      "quality_score": 94,
      "test_coverage": 89,
      "time_actual": "6.5 hours",
      "time_estimated": "5 hours"
    },
    "learnings": [
      "OAuth token refresh needs explicit testing",
      "Expand-migrate-contract took longer than estimated"
    ]
  },
  "tags": ["authentication", "oauth", "implementation"],
  "embedding": [0.123, -0.456, ...] // For similarity search
}

操作：

1. 存储事件：完成后保存事件
2. 回忆相似事件：查找相似的过往事件（向量相似度）
3. 按标签查询：检索带有特定标签的所有事件
4. 从结果中学习：从成功的事件中提取模式

查询：

# Find similar past implementations
recall-episode --similar "implementing OAuth" --top 5

# Find all authentication-related episodes
recall-episode --tag authentication

# Learn from failures
recall-episode --filter "quality_score < 80" --analyze

优势：

• 避免重复犯错
• 应用成功模式
• 提高估算准确性
• 加快决策速度

存储：

• 简单方案：将 JSON 文件存储在 .memory/episodic/YYYY-MM-DD/
• 高级方案：使用向量数据库进行语义搜索

---

记忆类型 2：程序记忆

定义：已掌握的技能、成功模式、自动化规则

适用场景：“我们通常如何做 X？”或“我们处理 Y 的标准方法是什么？”

存储：结构化文件或代码模式

结构：

{
  "skill_id": "implement_authentication",
  "skill_name": "Implementing Authentication Systems",
  "learned_from": [
    "ep_20250115_1530",
    "ep_20250120_1045",
    "ep_20250125_1400"
  ],
  "pattern": {
    "approach": "Expand-migrate-contract",
    "steps": [
      "1. Add new auth alongside existing",
      "2. Dual-write period (both methods work)",
      "3. Migrate users gradually",
      "4. Deprecate old auth"
    ],
    "pitfalls": [
      "Always test token refresh explicitly",
      "Plan for 20% longer than estimated (migrations complex)"
    ],
    "success_criteria": {
      "quality_score": ">= 90",
      "test_coverage": ">= 85",
      "backward_compatible": true
    }
  },
  "usage_count": 3,
  "success_rate": 1.0,
  "avg_quality_score": 93.3,
  "avg_time_hours": 6.2,
  "last_used": "2025-01-25T14:00:00Z"
}

操作：

1. 提取模式：从成功的事件中学习模式
2. 存储技能：保存已学到的程序性知识
3. 应用技能：将已学模式用于新任务
4. 改进技能：根据新经验进行更新

查询：

# Get learned pattern for authentication
get-skill "authentication implementation"

# Find most successful patterns
list-skills --sort-by success_rate --top 10

# Update skill with new learning
update-skill "authentication" --episode ep_20250125_1400

优势：

• 将成功模式编码保存
• 随时间推移改进模式
• 在团队间共享知识
• 加快实施速度（应用经过验证的模式）

存储：.memory/procedural/skills/

---

记忆类型 3：语义记忆

定义：事实、关系以及概念知识图谱

适用场景：“X 和 Y 之间有什么关系？”或“我们对 Z 有哪些了解？”

存储：图数据库（Neo4j）或包含关系的 JSON 文件

结构：

{
  "concepts": [
    {
      "id": "oauth",
      "type": "technology",
      "description": "OAuth 2.0 authorization framework",
      "properties": {
        "security_level": "high",
        "complexity": "medium",
        "browser_required": true
      },
      "relationships": [
        {
          "type": "used_by",
          "target": "user_authentication",
          "weight": 0.95
        },
        {
          "type": "requires",
          "target": "jwt",
          "weight": 0.85
        },
        {
          "type": "alternative_to",
          "target": "password_auth",
          "weight": 0.7
        }
      ]
    }
  ],
  "facts": [
    {
      "subject": "oauth",
      "predicate": "supports",
      "object": "multiple_providers",
      "confidence": 1.0,
      "source": "ep_20250115_1530"
    }
  ]
}

操作：

1. 存储事实：添加新知识
2. 查询知识：检索有关概念的事实
3. 查找关系：遍历知识图谱
4. 推断知识：根据关系推导新事实

查询：

# What do we know about OAuth?
query-knowledge "oauth"

# What are alternatives to password auth?
query-knowledge "password_auth" --relationship alternative_to

# Find all authentication methods
query-knowledge --type authentication_method

优势：

• 构建组织知识
• 理解概念之间的关系
• 做出有根据的决策
• 避免知识流失

存储：

• 简单方案：将 JSON 文件存储在 .memory/semantic/
• 高级方案：使用 Neo4j 图数据库

---

记忆类型 4：短期记忆

内容：活跃的工作上下文、当前会话状态

适用场景：需要在当前对话中记住信息

存储：RAM 或 Redis（快速访问）

结构：

{
  "session_id": "session_20250126_1200",
  "started_at": "2025-01-26T12:00:00Z",
  "current_task": "Implementing user authentication",
  "context": {
    "files_read": [
      "src/auth/login.ts",
      "src/auth/tokens.ts"
    ],
    "decisions_made": [
      {"what": "Use JWT", "why": "Stateless scaling"}
    ],
    "next_steps": [
      "Implement token refresh",
      "Add rate limiting"
    ]
  },
  "temporary_data": {
    "research_findings": "...",
    "plan_summary": "..."
  }
}

操作：

1. 设置上下文：存储当前工作数据
2. 获取上下文：检索活跃上下文
3. 更新上下文：修改当前状态
4. 清除上下文：重置工作记忆

优点：

• 快速访问当前状态
• 不会污染上下文窗口
• 高效管理会话

存储：文件位于 .memory/short-term/current-session.json

---

核心操作

操作 1：存储记忆

目的：将信息保存到合适的记忆类型中

流程：

// Store episodic memory
await storeMemory({
  type: 'episodic',
  event: {
    description: 'Implemented OAuth authentication',
    decisions: [...],
    outcomes: {...},
    learnings: [...]
  },
  tags: ['authentication', 'oauth', 'implementation']
});

// Store procedural memory (learned pattern)
await storeMemory({
  type: 'procedural',
  skillName: 'Implementing Authentication',
  pattern: {
    approach: 'Expand-migrate-contract',
    steps: [...],
    pitfalls: [...]
  }
});

// Store semantic memory (fact)
await storeMemory({
  type: 'semantic',
  fact: {
    subject: 'oauth',
    predicate: 'requires',
    object: 'jwt',
    confidence: 0.95
  }
});

输出：

• 记忆已持久化到存储中
• 已建立索引，便于检索
• 已添加时间戳

---

操作 2：回忆记忆

目的：检索与当前任务相关的记忆

流程：

// Recall similar episodes
const similarEpisodes = await recallMemory({
  type: 'episodic',
  query: 'implementing authentication',
  limit: 5
});

// Recall learned patterns
const authPattern = await recallMemory({
  type: 'procedural',
  skillName: 'Implementing Authentication'
});

// Query knowledge
const oauthFacts = await recallMemory({
  type: 'semantic',
  concept: 'oauth'
});

输出：

• 已检索到相关记忆
• 按相关性／新近程度排序
• 可用于辅助当前决策

---

操作 3：从经验中学习

目的：提取模式并更新程序性记忆

流程：

1. 分析事件：

   // Get all authentication implementations
   const authEpisodes = await recallMemory({
     type: 'episodic',
     tags: ['authentication', 'implementation']
   });
   
   // Extract patterns
   const patterns = analyzePatterns(authEpisodes);
   // - Approach used: expand-migrate-contract (3/3 times)
   // - Avg quality score: 93.3
   // - Common pitfall: Token refresh testing (3/3 missed initially)
   

2. 更新程序性记忆：

   await storeMemory({
     type: 'procedural',
     skillName: 'Implementing Authentication',
     pattern: {
       approach: 'expand-migrate-contract', // Learned from all 3 episodes
       common_pitfall: 'Always test token refresh explicitly', // Learned
       quality_target: '>= 93', // Based on historical avg
       time_estimate: '6-7 hours' // Based on historical data
     },
     learnedFrom: authEpisodes.map(ep => ep.id),
     confidence: 0.95 // High (based on 3 episodes)
   });
   

输出：

• 已将学到的模式整理成文
• 程序性记忆已更新
• 未来的决策将参考经验

---

操作 4：个性化

目的：根据用户偏好和模式进行调整

流程：

// Track user preferences
const preferences = await recall Memory({
  type: 'semantic',
  concept: 'user_preferences'
});

// Learn from usage patterns
const userPatterns = {
  preferred_approach: 'TDD', // User always uses TDD
  testing_thoroughness: 'high', // User requests >=95% coverage
  verification_level: 'all_layers', // User runs all 5 layers
  commit_style: 'conventional' // User uses conventional commits
};

// Apply personalization
if (userPatterns.preferred_approach === 'TDD') {
  // Auto-suggest TDD workflow
  // Skip asking "test-first or code-first?"
}

输出：

• 个性化建议
• 减少重复提问
• 加快工作流

---

跨会话集成

会话开始时的集成

Hook：SessionStart hook 加载记忆

#!/bin/bash
# .claude/hooks/load-memory.sh (SessionStart)

echo "📚 Loading agent memory..."

# Load short-term memory from last session
if [ -f ".memory/short-term/last-session.json" ]; then
  echo "  └─ Previous session context available"
  # Claude can read this file to continue work
fi

# Load recent episodic memories (last 7 days)
RECENT_EPISODES=$(find .memory/episodic/ -name "*.json" -mtime -7 | wc -l)
echo "  └─ Recent episodes: $RECENT_EPISODES"

# Load active skills
LEARNED_SKILLS=$(ls .memory/procedural/skills/ | wc -l)
echo "  └─ Learned skills: $LEARNED_SKILLS"

echo "✅ Memory loaded"

---

会话结束时的集成

Hook：SessionEnd hook 保存记忆

#!/bin/bash
# .claude/hooks/save-memory.sh (SessionEnd)

echo "💾 Saving agent memory..."

# Save current session to episodic memory
if [ -f ".memory/short-term/current-session.json" ]; then
  TIMESTAMP=$(date +%Y%m%d_%H%M%S)
  cp .memory/short-term/current-session.json \
     .memory/episodic/$(date +%Y-%m-%d)/session_$TIMESTAMP.json

  echo "  └─ Episode saved"
fi

# Extract learnings if quality was high
# (Automated learning extraction)

echo "✅ Memory saved"

---

记忆架构

基于文件的记忆（简单）

结构：

.memory/
├── episodic/              # Past events
│   ├── 2025-01-15/
│   │   ├── session_153000.json
│   │   └── decision_153045.json
│   └── 2025-01-16/
│       └── session_090000.json
├── procedural/            # Learned skills
│   └── skills/
│       ├── authentication_impl.json
│       ├── testing_pattern.json
│       └── verification_approach.json
├── semantic/              # Knowledge graph
│   ├── concepts.json
│   └── relationships.json
└── short-term/            # Active session
    ├── current-session.json
    └── last-session.json (backup)

优点：

• 简单（无需数据库）
• 可进行版本控制
• 人类可读
• 易于备份

局限：

• 不支持语义搜索
• 需要手动建立索引
• 处理大型数据集时速度较慢

---

基于数据库的记忆（高级）

情景记忆（向量数据库）：

• Pinecone：托管式、快速、昂贵
• Weaviate：可自托管、灵活
• Chroma：轻量，适合原型开发

语义记忆（图数据库）：

• Neo4j：行业标准
• AgensGraph：基于 PostgreSQL
• NetworkX：Python 库（简单图）

短期记忆（缓存）：

• Redis：快速、临时
• Memcached：简单缓存

优点：

• 语义搜索（相似性、关系）
• 大规模快速查询
• 高级功能

局限：

• 基础设施复杂
• 成本（托管式解决方案）
• 部署开销

---

与 Multi-AI 技能集成

与 multi-ai-implementation 集成

实施前（回忆相关模式）：

// Step 1: Explore - Check memory for similar implementations
const similarWork = await recallMemory({
  type: 'episodic',
  query: currentObjective,
  limit: 3
});

// Apply learnings
if (similarWork.length > 0) {
  console.log("📚 Found similar past work:");
  similarWork.forEach(episode => {
    console.log(`  - ${episode.description}`);
    console.log(`    Quality: ${episode.outcomes.quality_score}`);
    console.log(`    Learnings: ${episode.learnings.join(', ')}`);
  });
}

// Step 2: Plan - Use learned patterns
const authPattern = await recallMemory({
  type: 'procedural',
  skillName: 'Implementing Authentication'
});

if (authPattern) {
  console.log("📖 Applying learned pattern:");
  console.log(`  Approach: ${authPattern.pattern.approach}`);
  console.log(`  Estimated time: ${authPattern.avg_time_hours} hours`);
}

实施后（保存事件）：

// Step 6: Commit - Save to episodic memory
await storeMemory({
  type: 'episodic',
  event: {
    description: 'Implemented user authentication',
    decisions: capturedDuringImplementation,
    outcomes: {
      quality_score: 94,
      test_coverage: 89,
      time_actual: 6.5,
      time_estimated: 5
    },
    learnings: [
      'Token refresh needs explicit testing',
      'Estimation was 30% low'
    ]
  }
});

// Extract and update patterns
await learnFromExperience(['authentication', 'implementation']);

---

与 multi-ai-planning 集成

规划前：

// Recall similar plans
const similarPlans = await recallMemory({
  type: 'episodic',
  query: 'plan for ' + objective,
  filter: 'event_type == "planning"'
});

// Check quality of past plans
if (similarPlans.length > 0) {
  const avgQuality = average(similarPlans.map(p => p.outcomes.quality_score));
  console.log(`📊 Past similar plans averaged ${avgQuality}/100`);
}

规划后：

// Save plan to memory
await storeMemory({
  type: 'episodic',
  event: {
    event_type: 'planning',
    description: 'Planned OAuth implementation',
    context: {
      tasks: planGenerated.tasks.length,
      quality_score: planGenerated.quality_score,
      estimated_hours: planGenerated.metadata.estimated_total_hours
    }
  }
});

---

与 multi-ai-verification 集成

验证前：

// Recall common issues for this type of code
const commonIssues = await recallMemory({
  type: 'semantic',
  concept: 'authentication',
  relationship: 'common_issues'
});

// Focus verification on known problem areas
verificationFocus = commonIssues.map(issue => issue.description);

验证后：

// Save verification results
await storeMemory({
  type: 'episodic',
  event: {
    event_type: 'verification',
    description: 'Verified OAuth implementation',
    outcomes: {
      quality_score: 92,
      layers_passed: 5,
      issues_found: 3,
      time_minutes: 85
    }
  }
});

// Update semantic memory with new facts
if (issues_found.includes('bcrypt_rounds_low')) {
  await storeMemory({
    type: 'semantic',
    fact: {
      subject: 'bcrypt',
      predicate: 'recommended_rounds',
      object: '12-14',
      confidence: 0.95,
      source: 'verification_20250126'
    }
  });
}

---

记忆管理

记忆生命周期

创建（自动）：

• 每次技能执行完成后
• 做出重要决策后
• 验证完成时
• 失败时（用于学习）

保留（可配置）：

• 情景记忆：90 天（重要事件可延长保留时间）
• 程序性记忆：无限期（模式持续保留）
• 语义记忆：无限期（事实持续保留）
• 短期记忆：直到会话结束，并额外保留 1 份备份

清理（自动）：

• 旧的情景记忆：归档或删除
• 未使用的程序性模式：标记为非活动
• 低置信度事实：弃用
• 短期记忆：会话结束后清除

记忆整合

夜间流程：

#!/bin/bash
# Run nightly (cron job)

# 1. Consolidate recent episodes into patterns
node .memory/scripts/consolidate-episodes.js --days 7

# 2. Update procedural memory
node .memory/scripts/update-skills.js

# 3. Clean up old short-term memory
find .memory/short-term/ -name "*.json" -mtime +7 -delete

# 4. Archive old episodes
find .memory/episodic/ -name "*.json" -mtime +90 -exec mv {} .memory/archive/ \;

# 5. Update knowledge graph
node .memory/scripts/update-knowledge-graph.js

---

最佳实践

1. 每次发生重要事件后都进行存储

不要等到项目结束才保存——应持续保存

2. 尽量多添加标签

标签越多，越容易回忆（“身份验证”、“安全”、“oauth”、“实施”）

3. 在事件记录中包含上下文

存储足够的上下文，以便日后理解决策

4. 明确提取经验

不要只记录发生了什么，还要记录学到了什么

5. 定期回顾记忆

每月回顾：出现了哪些模式、有哪些改进、需要做出哪些改变

6. 在团队内共享记忆

语义记忆和程序记忆是团队资产

---

附录 A：通过 Hooks 集成记忆

SessionStart：加载记忆

{
  "event": "SessionStart",
  "description": "Load agent memory on session start",
  "handler": {
    "command": ".claude/hooks/load-memory.sh"
  }
}

SessionEnd：保存记忆

{
  "event": "SessionEnd",
  "description": "Save agent memory on session end",
  "handler": {
    "command": ".claude/hooks/save-memory.sh"
  }
}

PostToolUse：跟踪决策

{
  "event": "PostToolUse",
  "tools": ["Write"],
  "description": "Track significant code changes",
  "handler": {
    "command": ".claude/hooks/track-change.sh \"$FILE\" \"$TOOL\""
  }
}

---

附录 B：向量数据库集成

简单向量搜索（基于文件）

# Calculate similarity using embeddings
from sklearn.metrics.pairwise import cosine_similarity
import numpy as np

# Get embedding for current query
query_embedding = get_embedding(current_objective)

# Load all episode embeddings
episodes = load_all_episodes()

# Calculate similarities
similarities = cosine_similarity(
    [query_embedding],
    [ep['embedding'] for ep in episodes]
)[0]

# Get top 5 most similar
top_indices = np.argsort(similarities)[-5:][::-1]
similar_episodes = [episodes[i] for i in top_indices]

高级向量数据库（Pinecone）

import pinecone

# Initialize
pinecone.init(api_key="...", environment="...")
index = pinecone.Index("agent-memory")

# Store episode
index.upsert([
    ("ep_20250115_1530", episode_embedding, episode_metadata)
])

# Recall similar
results = index.query(
    query_embedding,
    top_k=5,
    include_metadata=True
)

similar_episodes = [r['metadata'] for r in results['matches']]

---

快速参考

4 种记忆类型

类型	存储方式	检索方式	保留期限	用途
事件记忆	向量数据库或带时间戳的 JSON	相似度搜索	90 天	“执行 X 时发生了什么？”
程序记忆	JSON 文件	按名称/标签查找	永久	“我们通常如何执行 Y？”
语义记忆	图数据库或 JSON	概念查询	永久	“我们对 Z 了解什么？”
短期记忆	RAM/Redis 或 JSON	直接访问	仅限会话	“当前上下文是什么？”

记忆操作

操作	目的	复杂度	耗时
存储	保存记忆	低	即时
回忆	检索记忆	低至中	文件 <1s，数据库 <100ms
学习	提取模式	中	数分钟
个性化	适应用户	中	持续进行

---

agent-memory-system 可在多个会话间持久保存记忆，让 Agent 能从经验中学习、持续改进并积累组织知识，这是构建真正自适应 AI 系统的基础。

有关集成示例，请参阅 examples/。有关数据库设置，请参阅附录 B。