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

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. 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 processes episodic memories through an LLM-driven merge using the SEMANTIC_MERGE_SYSTEM prompt defined in 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"). 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 (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 (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

npx @agentmemory/agentmemory consolidate-pipeline

2. REST API Endpoint

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.

3. MCP Tool

memory_consolidate

The MCP tool is registered in src/mcp/tools-registry.ts (lines 248-250) and invokes the pipeline via sdk.trigger in 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 handles episodic compression, while mem::consolidate-pipeline in src/functions/consolidation-pipeline.ts orchestrates semantic and procedural extraction.
• Automatic consolidation occurs every 2 hours via timers in 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 (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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}