> ## Documentation Index
> Fetch the complete documentation index at: https://agent-memory.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Memory Types and the Consolidation Pipeline
> Agent Memory organizes context into four tiers — working, episodic, semantic, and procedural — using an automated consolidation pipeline to surface what matters.
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** 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.
```typescript theme={null}
// 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
```typescript theme={null}
// 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
```typescript theme={null}
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
```typescript theme={null}
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.
```typescript theme={null}
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.
```typescript theme={null}
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`:
```env theme={null}
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`.