Agent Memory Systems

Overview

A skill for implementing memory management systems in AI agents — covering working memory, conversation history, persistent storage, and memory-augmented generation. Provides patterns for building agents that maintain state, recall past interactions, and learn from experience across sessions.

When to Use

• Designing agents with persistent state
• Building chatbots that remember user preferences
• Implementing conversation history management
• Creating knowledge-accumulating agents
• Managing context window limits efficiently

Quick Start

Copy
# Implement basic memory
claude "Add conversation memory to this chatbot agent"

# Persistent memory store
claude "Create a persistent memory system using SQLite for this agent"

Memory Tiers

Tier 1: Working Memory (In-Context)

Current conversation messages within the context window:

Copy
class WorkingMemory {
  private messages: Message[] = [];
  private maxTokens: number;

  add(message: Message) {
    this.messages.push(message);
    this.trim();
  }

  private trim() {
    while (this.tokenCount() > this.maxTokens) {
      // Remove oldest non-system messages
      const idx = this.messages.findIndex(m => m.role !== 'system');
      if (idx >= 0) this.messages.splice(idx, 1);
    }
  }
}

Tier 2: Session Memory (Short-Term)

Summarized conversation history for the current session:

Copy
class SessionMemory {
  private summaries: string[] = [];

  async summarizeAndStore(messages: Message[]) {
    const summary = await llm.call(
      `Summarize the key points from this conversation:\n${messages.map(m => `${m.role}: ${m.content}`).join('\n')}`
    );
    this.summaries.push(summary);
  }
}

Tier 3: Persistent Memory (Long-Term)

Stored across sessions in a database:

Copy
class PersistentMemory {
  async store(key: string, value: any, metadata?: Record<string, any>) {
    await db.memories.upsert({
      key,
      value: JSON.stringify(value),
      embedding: await embed(JSON.stringify(value)),
      ...metadata,
      updatedAt: new Date(),
    });
  }

  async recall(query: string, limit = 5): Promise<Memory[]> {
    const embedding = await embed(query);
    return db.memories.similaritySearch(embedding, limit);
  }
}

Memory Operations

Operation	Description	When
Store	Save new information	After decisions, new facts
Retrieve	Find relevant past info	Before responding
Update	Modify existing memory	When facts change
Summarize	Compress verbose memories	When approaching limits
Forget	Remove outdated info	During maintenance
Consolidate	Merge related memories	Periodically

Context Window Strategy

Total budget: 200K tokens
├── System prompt:     2K (1%)
├── Retrieved memory:  20K (10%)
├── Recent messages:   40K (20%)
├── Current context:   118K (59%)
└── Response reserve:  20K (10%)

Best Practices

1. Tiered storage — Use working memory for current context, persistent for long-term
2. Semantic retrieval — Use embeddings, not keyword matching
3. Summarize aggressively — Compress old context to save tokens
4. Relevance scoring — Only inject memories above a similarity threshold
5. Decay unused memories — Reduce priority of memories not accessed recently
6. Separate concerns — Keep user preferences, project facts, and conversation history separate
7. Handle staleness — Mark memory update timestamps, prefer recent over old
8. Test recall — Verify your retrieval system returns actually relevant results