ai-agent-memory

Files (1)

• SKILL.md

SKILL.md (first lines)

# AI Agent Memory

## Overview

LLM agents have zero intrinsic memory — each API call starts fresh. Building useful agents requires designing explicit memory systems: in-context (what fits in the prompt), episodic (past conversation/event history in vector stores), semantic (facts and entities in knowledge graphs), and procedural (learned action patterns). The challenge is retrieval — storing is easy, but fetching the right memories at the right time without overwhelming the context window is an engineering problem. Multi-tier architectures mirror human memory: fast working memory (in-context), slower episodic memory (vector search), and persistent semantic memory (graph database or KV store).

## When to Use

- Agents that need to remember user preferences, past conversations, or domain knowledge
- Customer service bots that must recall previous interactions across sessions
- Research agents accumulating knowledge over many investigation steps
- Personal AI assistants with persistent user-specific context
- Coding agents that learn project conventions over time
- Any agent system where cold-start (forgetting everything between sessions) degrades quality

## Step-by-Step Workflow

### 1. In-Context Memory Management

```python
# src/agent/context_manager.py
from anthropic import Anthropic
from dataclasses import dataclass
from typing import Optional
import tiktoken

@dataclass
class Message:
    role: str   # "user" | "assistant"
    content: str
    tokens: int = 0

class ContextWindowManager:
    """Manage conversation history within token limits."""

    def __init__(self, max_tokens: int = 150_000, model: str = "claude-sonnet-4-6"):
        self.max_tokens = max_tokens
        self.reserve_for_response = 4096
        self.messages: list[Message] = []
        self.client = Anthropic()

    def count_tokens(self, text: str) -> int:
        # Rough estimate: 4 chars per token
        return len(text) // 4

    def add_message(self, role: str, content: str):
        tokens = self.count_tokens(content)
        self.messages.append(Message(role=role, content=content, tokens=tokens))
        self._trim_if_needed()

    def _trim_if_needed(self):
        """Remove oldest messages (preserving system context) when over limit."""
        total_tokens = sum(m.tokens for m in self.messages)
        budget = self.max_tokens - self.reserve_for_response

        # Always keep the last N messages for coherence
        min_keep = 4

        while total_tokens > budget and len(self.messages) > min_keep:
            # Remove oldest message (index 0)
            removed = self.messages.pop(0)
            total_tokens -= removed.tokens

    def get_messages_for_api(self) -> list[dict]:
        return [{"role": m.role, "content": m.content} for m in self.messages]

    def summarize_old_messages(self, messages_to_summarize: list[Message]) -> str:
        """Use LLM to compress old conversation into a summary."""
        transcript = "\n".join(
            f"{m.role}: {m.content}" for m in messages_to_summarize
        )
        response = self.client.messages.create(
            model="claude-haiku-4-5",  # Use cheap model for summarization
            max_tokens=512,
            messages=[{
                "role": "user",
                "content": f"Summarize this conversation in 3-5 bullet points:\n\n{transcript}"
            }],
        )
        return response.content[0].text
```

### 2. Episodic Memory with Vector Store

```python
# src/agent/episodic_memory.py
from openai import OpenAI
from qdrant_client import QdrantClient
from qdrant_client.models import Distance, VectorParams, PointStruct
from datetime import datetime
import uuid
import json

class EpisodicMemory:
    """Store and retrieve past agent experiences using semantic search."""

    def __init__(self, collection_name: str = "agent_episodes"):
        self.openai = OpenAI()
        self.qdrant = QdrantClient(url="http://localhost:6333")
        self.collection = collection_name
        self.embed_dim = 1536  # text-embedding-3-small

        # Create collection if not exists
        self._init_collection()

    def _init_collection(self):
        collections = [c.name for c in self.qdrant.get_collections().collections]
        if self.collection not in collections:
            self.qdrant.create_collection(
                self.collection,
                vectors_config=VectorParams(size=self.embed_dim, distance=Distance.COSINE),
            )

    def _embed(self, text: str) -> list[float]:
        resp = self.openai.embeddings.create(
            model="text-embedding-3-small",
            input=text,
        )
        return resp.data[0].embedding

From UltronCore/claude-skill-vault, MIT.

More from UltronCore/claude-skill-vault