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.
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 |
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[];
}
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:
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 |
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. 