Memory Types and the Consolidation Pipeline

Agent Memory doesn’t store everything forever in a flat list. Instead, it organizes your agent’s experience into four tiers of memory — each with a different lifespan, compression level, and retrieval role. Raw observations from today sit in working memory. Summaries of what happened last week live in episodic memory. The patterns your agent has learned across many sessions are distilled into semantic and procedural memory. This hierarchy means the right memories surface at the right time, without flooding your context window with irrelevant history.

The Four Tiers

Working Memory
Episodic Memory
Semantic Memory
Procedural Memory

Working memory holds the raw observations from your current and recent sessions. Every file read, every command, every error — all captured via hooks and stored immediately as RawObservation and then CompressedObservation records.

Lifespan: Current session and a rolling recent window
Content: Individual tool-use events, user prompts, agent responses, errors
Recency weight: Highest — working memory observations score strongly in retrieval for active projects
Analogy: Short-term memory — the scratchpad of what just happened

Working memory is the source of truth for real-time capture. Every other tier is derived from it through the consolidation pipeline.

// A raw observation — exactly what Agent Memory captures at hook time
interface RawObservation {
  id: string;
  sessionId: string;
  timestamp: string;
  hookType: HookType;        // which hook fired (pre_tool_use, post_tool_use, etc.)
  toolName?: string;         // e.g. "Read", "Bash", "Edit"
  toolInput?: unknown;       // the arguments passed to the tool
  toolOutput?: unknown;      // what the tool returned
  userPrompt?: string;       // the user's prompt (privacy-filtered)
  assistantResponse?: string;
  raw: unknown;              // the full hook payload
}

Episodic memory holds compressed summaries of completed sessions. When a session ends, Agent Memory generates a SessionSummary that distills the session into a narrative, key decisions, modified files, and core concepts.

Lifespan: Persistent across sessions; decays gradually over weeks unless reinforced
Content: What happened, when, in which project, which files changed, what decisions were made
Recency weight: High for recent projects; decays based on CONSOLIDATION_DECAY_DAYS (default: 30 days)
Analogy: “What happened” — autobiographical record of past sessions

// Generated at session end during consolidation
interface SessionSummary {
  sessionId: string;
  project: string;
  createdAt: string;
  title: string;           // e.g. "Implemented JWT auth middleware"
  narrative: string;       // prose summary of what the session accomplished
  keyDecisions: string[];  // e.g. ["Chose jose over jsonwebtoken for Edge compat"]
  filesModified: string[]; // e.g. ["src/middleware/auth.ts", "test/auth.test.ts"]
  concepts: string[];      // e.g. ["authentication", "JWT", "Edge runtime"]
  observationCount: number;
}

Semantic memory holds distilled facts, patterns, and concepts extracted across multiple sessions. While episodic memory says “in session X we used jose for JWT”, semantic memory says “this project uses jose for JWT auth in Edge-compatible middleware.”

Lifespan: Long-term; strengthens with repeated reinforcement, decays without it
Content: Facts about your codebase, architectural decisions, preferences, discovered patterns
Recency weight: Access-based — frequently retrieved facts score higher
Analogy: “What I know” — generalized knowledge distilled from experience

interface SemanticMemory {
  id: string;
  fact: string;            // e.g. "Auth uses jose middleware in src/middleware/auth.ts"
  confidence: number;      // 0–1, increases with reinforcement
  sourceSessionIds: string[];
  sourceMemoryIds: string[];
  accessCount: number;     // how many times this fact has been retrieved
  lastAccessedAt: string;
  strength: number;        // combined recency + access score
  createdAt: string;
  updatedAt: string;
}

Procedural memory holds recurring workflows, conventions, and step-by-step patterns your agent has learned. If your agent always runs npm test before committing, or always checks for TypeScript errors before running the dev server, those patterns become procedural memories.

Lifespan: Long-term; reinforced when the workflow recurs
Content: Named workflows with ordered steps, trigger conditions, and expected outcomes
Recency weight: Frequency-weighted — workflows done more often score higher
Analogy: “How to do it” — muscle memory for repeatable processes

interface ProceduralMemory {
  id: string;
  name: string;              // e.g. "TypeScript build validation"
  steps: string[];           // ordered list of steps
  triggerCondition: string;  // when this procedure applies
  expectedOutcome?: string;  // what success looks like
  frequency: number;         // how many times this procedure was observed
  sourceSessionIds: string[];
  tags?: string[];
  concepts?: string[];
  strength: number;
}

The Consolidation Pipeline

Consolidation is the process that promotes observations from working memory through the higher tiers. It runs automatically at session end when you have an LLM provider configured.

Raw observations (working memory)
        ↓  [session end hook fires]
Session summary (episodic)
        ↓  [LLM summarization]
SemanticMemory facts extracted across sessions
        ↓  [pattern detection]
ProceduralMemory workflows learned
        ↓  [optional: GRAPH_EXTRACTION_ENABLED=true]
Knowledge graph (entities + relationships)

Enable CONSOLIDATION_ENABLED=true in ~/.agentmemory/.env for the full pipeline. If you have an LLM provider key configured (ANTHROPIC_API_KEY, GEMINI_API_KEY, OPENAI_API_KEY, etc.), consolidation is on by default — you don’t need to set the flag explicitly. Disable it with CONSOLIDATION_ENABLED=false if you want fully LLM-free operation.

Without an LLM, the pipeline stops at the episodic tier — session summaries are generated using BM25-compatible synthetic compression, but semantic and procedural extraction require an LLM call. You can also trigger consolidation manually at any time using the memory_consolidate MCP tool or by calling POST /agentmemory/consolidate.

Memory Strength

Every memory in Agent Memory has a strength score. Strength is a composite of:

Recency — how recently the memory was created or last accessed
Access frequency — how many times the memory has been retrieved in search results
Reinforcement — whether the underlying fact has been confirmed by multiple independent sessions

Strong memories surface first in search results. Weak memories — old, rarely accessed, unconfirmed — gradually decay and eventually become candidates for eviction. This mirrors the Ebbinghaus forgetting curve: things you use stay sharp; things you don’t use fade.

interface Memory {
  id: string;
  type: "pattern" | "preference" | "architecture" | "bug" | "workflow" | "fact";
  title: string;
  content: string;
  strength: number;     // higher = surfaces first in search
  version: number;      // increments when a memory is updated
  isLatest: boolean;    // false for superseded versions
  forgetAfter?: string; // optional TTL — memory auto-evicts after this date
  // ...
}

Long-term vs Short-term Memory Objects

Agent Memory uses three distinct data structures depending on where in the lifecycle an observation lives:

Type	Stage	Description
`RawObservation`	Capture	Unprocessed hook payload — the exact tool name, input, output, and timestamp
`CompressedObservation`	Processing	LLM-compressed (or synthetically compressed) version with facts, concepts, narrative, and importance score
`Memory`	Long-term	Versioned, typed, strength-scored long-term memory with cross-session provenance

You interact primarily with Memory objects through the MCP tools and REST API. RawObservation and CompressedObservation records are accessible via memory_recall and the timeline view, but they’re mostly managed by Agent Memory internally.

Lessons

Lessons are a special memory type for high-confidence, explicitly learned insights. Unlike regular memories that are extracted automatically, lessons are created intentionally — either by the consolidation pipeline from a Crystal (a compact record of a completed action chain), manually via the memory_lesson_save MCP tool, or by the consolidation pass itself.

interface Lesson {
  id: string;
  content: string;       // the lesson text
  context: string;       // what situation this lesson applies to
  confidence: number;    // 0–1 confidence score
  reinforcements: number; // how many times this lesson has been confirmed
  source: "crystal" | "manual" | "consolidation";
  decayRate: number;     // lessons decay if not reinforced
  project?: string;      // scoped to a project, or global
  tags: string[];
}

Lessons decay over time if not reinforced — if your agent never encounters the situation again, the lesson’s confidence gradually drops. When it is encountered and the lesson proves relevant, reinforcements increments and confidence rises. This keeps your lesson library current and removes lessons that no longer apply to your workflow. Control lesson decay with LESSON_DECAY_ENABLED=true (on by default).

Memory Slots

Memory slots are pinned memory units that persist across sessions and projects. Think of them as always-available context blocks that your agent can read and write — a persona slot, a user_preferences slot, project_context, pending_items, and more. Enable slots in ~/.agentmemory/.env:

AGENTMEMORY_SLOTS=true

With slots enabled, you get eight built-in slots:

Slot	Purpose
`persona`	How your agent should behave and communicate
`user_preferences`	Your coding style, preferred tools, conventions
`tool_guidelines`	When and how to use specific tools
`project_context`	Files, technologies, and architecture for your current project
`guidance`	High-priority instructions for the current session
`pending_items`	TODOs carried forward from past sessions
`session_patterns`	Recurring patterns Agent Memory has observed
`self_notes`	Agent-written notes for itself between sessions

Slots are size-limited and pinned — they’re always injected at session start, regardless of the token budget. Manage them using the memory_slot_* MCP tools. Pair slots with AGENTMEMORY_REFLECT=true to enable automatic slot updates at session end: Agent Memory scans recent observations and auto-appends TODOs to pending_items, counts patterns in session_patterns, and records touched files in project_context.

Get Started

Core Concepts

Guides

Integrations

Memory Types and the Consolidation Pipeline

The Four Tiers

The Consolidation Pipeline

Memory Strength

Long-term vs Short-term Memory Objects

Lessons

Memory Slots

​The Four Tiers

​The Consolidation Pipeline

​Memory Strength

​Long-term vs Short-term Memory Objects

​Lessons

​Memory Slots

The Four Tiers

The Consolidation Pipeline

Memory Strength

Long-term vs Short-term Memory Objects

Lessons

Memory Slots