# Agentmemory's 4-Tier Memory Consolidation System: From Working Memory to Procedural Knowledge

> Discover Agentmemory's 4-tier memory consolidation system. Learn how it transforms raw tool observations into procedural knowledge using LLM-driven pipelines and a biological memory hierarchy.

- Repository: [Rohit Ghumare/agentmemory](https://github.com/rohitg00/agentmemory)
- Tags: deep-dive
- Published: 2026-05-10

---

**Agentmemory implements a biologically-inspired memory hierarchy that automatically compresses raw tool observations into durable procedural knowledge through four distinct tiers—working, episodic, semantic, and procedural—using LLM-driven consolidation pipelines.**

Agentmemory is an open-source memory layer for AI agents that captures tool usage patterns and converts them into reusable knowledge. According to the rohitg00/agentmemory repository, the system employs a **4-tier memory consolidation system** modeled on human cognitive architecture to progressively distill fleeting observations into stable, actionable workflows.

## The Four Memory Tiers

Agentmemory structures knowledge acquisition analogous to human memory formation, with each tier representing a different level of abstraction and permanence.

### Working Memory: Raw Observation Capture

The **working memory** tier acts as the system's short-term buffer, storing raw, time-stamped observations immediately after tool execution. 

When an agent invokes a tool, the `PostToolUse` hook captures the tool name, input parameters, and output results, writing these observations directly to the KV store. This tier maintains unprocessed, granular telemetry that serves as the foundation for higher-level consolidation.

### Episodic Memory: Session Summaries

**Episodic memory** stores session-level narratives that describe *what happened* during specific interaction periods.

At the end of each session, the `SessionEnd` hook triggers the `mem::consolidate` function in [`src/functions/consolidate.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/functions/consolidate.ts). This function merges overlapping working memory observations into coherent session records, eliminating redundancy while preserving contextual continuity. The result is a compressed narrative of agent activities rather than isolated tool calls.

### Semantic Memory: Factual Knowledge Extraction

The **semantic memory** tier represents *what the system knows*—stable facts, concepts, and patterns extracted from episodic experiences.

The `mem::consolidate-pipeline` function in [`src/functions/consolidation-pipeline.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/functions/consolidation-pipeline.ts) processes episodic memories through an LLM-driven merge using the `SEMANTIC_MERGE_SYSTEM` prompt defined in [`src/prompts/consolidation.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/prompts/consolidation.ts). This synthesis identifies recurring entities, relationships, and factual claims across multiple sessions, converting transient narratives into enduring knowledge representations.

### Procedural Memory: Actionable Workflows

**Procedural memory** captures *how to do things*—actionable workflows, decision patterns, and operational rules derived from semantic knowledge.

Following semantic consolidation, the pipeline executes a second LLM pass that extracts procedural rules (for example, "to add JWT auth, modify [`src/middleware/auth.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/middleware/auth.ts)"). These rules encode successful action sequences as reusable long-term procedural memories that guide future agent behavior.

## How the Consolidation Pipeline Works

The consolidation process runs automatically on a timer every **2 hours** by default, as implemented in [`src/index.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/index.ts) (lines 467-505). During execution, the system performs three critical maintenance operations:

- **Memory decay**: Old memories fade according to an Ebbinghaus-style forgetting curve, preventing storage saturation
- **Strengthening**: Frequently accessed items receive reinforcement, improving retrieval priority
- **Contradiction resolution**: The pipeline detects and reconciles conflicting information to maintain knowledge base consistency

All consolidation steps record audit entries via `recordAudit` in [`src/functions/consolidation-pipeline.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/functions/consolidation-pipeline.ts) (line 261), ensuring complete traceability of how raw observations evolved into procedural knowledge.

## Triggering the Consolidation Pipeline

You can initiate the full 4-tier consolidation through three interfaces:

**1. Command Line Interface**

```bash
npx @agentmemory/agentmemory consolidate-pipeline

```

**2. REST API Endpoint**

```bash
curl -X POST http://localhost:3111/agentmemory/consolidate-pipeline \
     -H "Authorization: Bearer $AGENTMEMORY_SECRET"

```

This endpoint maps to `api::consolidate-pipeline` in [`src/triggers/api.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/triggers/api.ts).

**3. MCP Tool**

```javascript
memory_consolidate

```

The MCP tool is registered in [`src/mcp/tools-registry.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/mcp/tools-registry.ts) (lines 248-250) and invokes the pipeline via `sdk.trigger` in [`src/mcp/server.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/mcp/server.ts).

## Summary

- Agentmemory organizes knowledge into **four tiers**: working (raw observations), episodic (session narratives), semantic (facts), and procedural (workflows).
- The `mem::consolidate` function in [`src/functions/consolidate.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/functions/consolidate.ts) handles episodic compression, while `mem::consolidate-pipeline` in [`src/functions/consolidation-pipeline.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/functions/consolidation-pipeline.ts) orchestrates semantic and procedural extraction.
- Automatic consolidation occurs every 2 hours via timers in [`src/index.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/index.ts), with manual triggers available through CLI, REST API (`POST /agentmemory/consolidate-pipeline`), or MCP (`memory_consolidate`).
- The system maintains memory health through decay curves, access strengthening, and contradiction detection, with full audit trails via `recordAudit`.

## Frequently Asked Questions

### What is the difference between episodic and semantic memory in agentmemory?

**Episodic memory** stores contextual narratives of what happened during specific sessions, generated by the `mem::consolidate` function when sessions end. **Semantic memory** extracts decontextualized facts and concepts from multiple episodic records using the `SEMANTIC_MERGE_SYSTEM` prompt, creating stable knowledge independent of specific temporal instances.

### How often does agentmemory run automatic consolidation?

By default, the consolidation pipeline triggers automatically every **2 hours** based on the timer configuration in [`src/index.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/index.ts) (lines 467-505). This interval balances computational overhead with knowledge freshness.

### Can I trigger consolidation manually without waiting for the timer?

Yes. You can manually trigger the full pipeline through three methods: the CLI command `npx @agentmemory/agentmemory consolidate-pipeline`, a POST request to `/agentmemory/consolidate-pipeline`, or the MCP tool `memory_consolidate` registered in [`src/mcp/tools-registry.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/mcp/tools-registry.ts).

### How does agentmemory handle conflicting information across sessions?

During consolidation, the pipeline includes a **contradiction detection and resolution** phase that identifies conflicting facts or rules. The system reconciles these conflicts using LLM-based reasoning to maintain a consistent knowledge base, logging all resolutions via `recordAudit` for transparency.