agent-memory

btafoya 的头像作者 btafoya

AI代理的持久性记忆系统,包含语义性、情节性和程序性记忆类型。当用户想要(1)跨会话记住事实、偏好或上下文,(2)跟踪交互历史和经验,(3)存储可重用的工作流或程序,(4)构建从对话中学习的个性化代理,或(5)为AI应用程序实现任何形式的长期记忆时使用。

📖 中文导读:AI代理的持久性记忆系统,包含语义性、情节性和程序性记忆类型。当用户想要(1)跨会话记住事实、偏好或上下文,(2)跟踪交互历史和经验,(3)存储可重用的工作流或程序,(4)构建从对话中学习的个性化代理,或(5)为AI应用程序实现任何形式的长期记忆时使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: agent-memory description: Persistent memory system for AI agents with semantic, episodic, and procedural memory types. Use when users want to (1) remember facts, preferences, or context across sessions, (2) track interaction history and experiences, (3) store reusable workflows or procedures, (4) build personalized agents that learn from conversations, or (5) implement any form of long-term memory for AI applications.

Agent Memory Skill

Implements a 4-layer cognitive memory architecture for AI agents:

Internal Knowledge (LLM weights) ← frozen
         ↑
Context Window (per inference) ← this skill helps populate
         ↑
Short-Term Memory (session state)
         ↑
Long-Term Memory (persistent storage)
├── Semantic (facts)
├── Episodic (experiences)
└── Procedural (workflows)

Quick Start

from memory import MemoryStore

store = MemoryStore()

# Add semantic memory (facts)
store.add_fact("User prefers TypeScript over JavaScript")

# Add episodic memory (timestamped experience)
store.add_episode("Helped debug authentication issue", topic="auth")

# Add procedural memory (workflow)
store.add_procedure("deploy", ["Run tests", "Build", "Push", "Deploy"])

# Search and retrieve
results = store.search("TypeScript")
context = store.build_context("authentication")  # For prompt injection

Memory Types

Type Purpose Example
Semantic Facts, preferences, relationships "User is a Python developer"
Episodic Timestamped experiences "[2025-01-15] Debugged JWT expiry issue"
Procedural Workflows, multi-step procedures "Code review: 1. Check types, 2. Review errors..."

Core Operations

Adding Memories

# Semantic: timeless facts
store.add_fact("Project uses PostgreSQL", project="myapp")

# Episodic: what happened when
store.add_episode("User frustrated with Docker networking", emotion="frustrated")

# Procedural: how to do things
store.add_procedure("code_review", [
    "Check type hints",
    "Review error handling",
    "Verify test coverage"
], trigger="user asks for code review")

Updating Facts

Handle the "brother changed jobs" problem—don't just add new facts, update existing ones:

store.update_fact(
    "User's brother is a software engineer",
    "User's brother is now a doctor"
)

Retrieval

# Search (graph backend enables relationship traversal)
results = store.search("database", category="semantic", limit=5)

# Get specific memory types
facts = store.get_by_category("semantic")
recent = store.get_recent_episodes(limit=10)
procedure = store.get_procedure("deploy")

Context Engineering

Build context for LLM prompts from relevant memories:

context = store.build_context(
    query="API authentication",
    max_facts=10,
    max_episodes=5,
    include_procedures=True
)
# Returns formatted string ready for prompt injection

Integration Patterns

Pattern 1: CLAUDE.md Injection

Export memories and paste into project's CLAUDE.md:

python -c "from memory import get_store; print(get_store().export_for_prompt())"

Pattern 2: MCP Server

Run scripts/mcp_server.py as an MCP server for direct tool access.

Setup:

# Install dependencies with pipx
pipx install mcp
pipx install cogdb  # For graph backend (default)

Add to Claude Code config (~/.config/claude-code/config.json):

{
  "mcpServers": {
    "memory": {
      "command": "python",
      "args": ["/path/to/agent-memory-skill/scripts/mcp_server.py"]
    }
  }
}

Available tools: memory_add_fact, memory_add_episode, memory_add_procedure, memory_search, memory_get_context, memory_stats

Pattern 3: Session Hooks

# At session start: load relevant context
context = store.build_context(user_query)

# During session: record significant interactions  
store.add_episode("Helped with X", outcome="success")

# At session end: extract and save new facts
store.add_fact("User prefers functional patterns")

Storage

By default, memories persist to ~/.claude_memory/graph/ using CogDB for relationship-aware storage.

For zero-dependency fallback, use MemoryStore(backend="json") which stores to ~/.claude_memory/memories.json.

For enhanced production use, consider adding vector similarity using embeddings (OpenAI, sentence-transformers) alongside the graph storage.

References

  • See references/memory-theory.md for cognitive science background
  • See references/storage-patterns.md for advanced storage options (entities, knowledge graphs)