Memory Persistence

# Memory Persistence

Part of [Agent Skills™](https://github.com/itallstartedwithaidea/agent-skills) by [googleadsagent.ai™](https://googleadsagent.ai)

## Description

Memory Persistence enables AI agents to maintain knowledge across sessions, transforming stateless inference calls into stateful, continuously improving systems. Without persistence, every new session starts from zero — the agent must re-learn user preferences, re-discover codebase patterns, and repeat mistakes it has already corrected. Memory Persistence solves this by implementing hooks that save critical context at session end and reload it at session start, creating the illusion of continuous memory.

This skill is built on the production memory system powering Buddy™ at [googleadsagent.ai™](https://googleadsagent.ai), which uses Cloudflare KV as a persistent memory store. After each conversation, Buddy™ extracts entities (campaigns, metrics, user preferences, decisions made), summarizes the session, and stores the result keyed by user and session. On the next conversation, the most relevant memories are retrieved and injected into context, giving Buddy™ the ability to reference prior analyses, respect stated preferences, and build on previous decisions.

The memory system operates at three granularities: entity-level memory (individual facts like "user prefers conservative bidding"), session-level memory (summarized conversations), and pattern-level memory (recurring behaviors like "this account always overspends on branded terms"). Each granularity serves different retrieval patterns and has different storage and freshness requirements.

## Use When

- Users interact with the agent across multiple sessions and expect continuity
- The agent makes decisions that should remain consistent over time (preferences, conventions)
- Domain knowledge accumulates over sessions and should not be lost
- You want to avoid repetitive re-explanation of codebase structure or project context
- The agent needs to track evolving entities (accounts, campaigns, metrics) across time
- Session summarization is needed for audit trails or compliance

## How It Works

```mermaid
graph TD
    A[Session Start] --> B[Memory Retrieval]
    B --> C[Context Assembly]
    C --> D[Agent Execution]
    D --> E[Session End Trigger]
    E --> F[Entity Extraction]
    F --> G[Session Summarization]
    G --> H[Memory Indexing]
    H --> I[KV Store Write]
    
    B --> J[KV Store Read]
    J --> K{Match Found?}
    K -->|Yes| L[Relevance Ranking]
    L --> M[Top-K Selection]
    M --> C
    K -->|No| C
```

At session start, the memory retrieval system queries the KV store for memories relevant to the current user and task. Retrieved memories are ranked by relevance and recency, and the top-K are injected into the agent's context. During the session, the agent operates normally. At session end (triggered by hooks or explicit save), the entity extractor identifies key facts, decisions, and preferences from the conversation. The session summarizer produces a compact summary. Both entities and the summary are indexed and written to the KV store for future retrieval.

## Implementation

**Memory Store Interface (Cloudflare KV):**

```typescript
interface Memory {
  id: string;
  userId: string;
  type: "entity" | "session_summary" | "pattern";
  content: string;
  metadata: {
    sessionId: string;
    timestamp: number;
    importance: number;
    tags: string[];
  };
}

class MemoryStore {
  constructor(private kv: KVNamespace) {}

  async save(memory: Memory): Promise<void> {
    const key = `memory:${memory.userId}:${memory.type}:${memory.id}`;
    await this.kv.put(key, JSON.stringify(memory), {
      metadata: { importance: memory.metadata.importance, timestamp: memory.metadata.time