How to Use memory_consolidate for Karpathy-Style LLM Wiki Compilation

The memory_consolidate tool is an MCP server capability in the ai-memory repository that orchestrates a seven-phase pipeline to compile raw session observations into a structured, inter-linked markdown wiki, implementing Andrej Karpathy's "LLM Wiki" architectural pattern.

The ai-memory project by akitaonrails implements a sophisticated knowledge management system that transforms ephemeral LLM interactions into persistent, human-readable documentation. At the core of this system lies memory_consolidate, a specialized tool that executes the end-to-end compilation flow from raw observations to consolidated wiki pages. This article examines how to leverage this tool to build maintainable, version-controlled knowledge bases following Karpathy's three-layer architecture.

The Consolidation Pipeline Architecture

The memory_consolidate implementation follows a strict sequence defined across crates/ai-memory-consolidate/src/consolidator.rs and related modules, moving from raw data ingestion to atomic persistence.

Phase 1: Observation Collection

During active sessions, the hook server stores each observation via the SessionConsolidation struct in crates/ai-memory-store/src/session_consolidation.rs. This component maintains the queue of observations awaiting consolidation, holding the raw inputs that will later be transformed into wiki content.

Phase 2: Building the LLM Request

The system calls ai_memory_consolidate::build_batch_request(session_id, &observations) defined in crates/ai-memory-consolidate/src/types.rs (lines 158-172). This function transforms the observation set into batched LLM prompts digestible by the configured provider.

Phase 3: LLM Generation with Advisory Prompts

Before generation, the consolidator reads the project's _prompts/consolidation.md file, capping content at 2,000 characters to create a sanitized advisory prompt. Users can override this file for single invocations using the instructions parameter. The batch executes against the provider configured via ai_memory_consolidate::DEFAULT_… constants defined in src/consolidator.rs.

Phase 4: Atomic Multi-Page Writes

By default, memory_consolidate operates with multi_page=true, fanning out results to separate wiki pages. Each write occurs atomically via ai_memory_wiki::Wiki::write_page in crates/ai-memory-wiki/src/wiki.rs (lines 4187-4224), wrapped in a single SQLite transaction to guarantee consistency.

Phase 5: Recording and Handoff

The pipeline updates sessions/<id>.md with the consolidated body and emits a handoff event for downstream tools. This admission operation is defined in crates/ai-memory-wiki/src/admission.rs at the AdmissionOp::Consolidate variant (line 92), mapping to the HTTP header X-Memory-Op: consolidate.

Trigger Points and Configuration

Understanding when and how the consolidation executes is critical for operational deployment.

Invocation Modes

The tool supports three distinct trigger mechanisms:

• Manual execution: Direct CLI or MCP tool calls for on-demand compilation
• Session-end hooks: Automatic triggering when the environment variable AI_MEMORY_CONSOLIDATE_ON_SESSION_END is enabled
• PreCompact sweeps: Background consolidation during maintenance cycles

Fallback Behavior

If no LLM provider is configured, the call becomes a no-op and gracefully falls back to rule-based summary generation, ensuring the system remains operational even without LLM connectivity.

Practical Implementation Examples

Rust API Integration

Use the internal crates to programmatically trigger consolidation within custom tools:

// Build the batch request that the LLM will consume
let session_id = ...;                 // UUID of the finished session
let observations = store.get_observations(session_id)?;
let batch = ai_memory_consolidate::build_batch_request(session_id, &observations);

// Run the consolidation (this is what the `memory_consolidate` tool does)
let result = ai_memory_consolidate::run(batch, /*multi_page=*/ true, None)?;

// Persist the generated pages back to the wiki
for page in result.pages {
    wiki.write_page(&page.path, &page.body, /*author=*/ result.author)?;
}

Command-Line Interface

Invoke the tool manually from the terminal for specific session IDs:

# Manual consolidation of the current session

ai-memory consolidate --session-id 123e4567-e89b-12d3-a456-426614174000

# One-off override of the advisory prompt

ai-memory consolidate --session-id $SID --instructions "Summarize only the security decisions."

MCP Tool Protocol

Call the tool directly through the Model Context Protocol when building agent integrations:

{
  "tool": "memory_consolidate",
  "params": {
    "session_id": "123e4567-e89b-12d3-a456-426614174000",
    "multi_page": true,
    "instructions": null
  }
}

Core Source Files

Production deployments of memory_consolidate rely on these specific implementation files:

• crates/ai-memory-consolidate/src/types.rs: Contains build_batch_request for converting observations into LLM prompts
• crates/ai-memory-consolidate/src/consolidator.rs: Houses the core LLM driver, response parsing, and page generation loop
• crates/ai-memory-wiki/src/wiki.rs: Implements write_page using atomic tmp-plus-rename-fsync patterns (lines 4187-4224)
• crates/ai-memory-wiki/src/admission.rs: Defines the Consolidate admission operation and HTTP header mappings
• docs/ARCHITECTURE.md: Documents the high-level pipeline and its relationship to Karpathy's LLM Wiki pattern

Summary

• memory_consolidate implements the complete Karpathy-style compilation pipeline from raw observations to structured markdown
• The seven-phase flow includes collection, batching, LLM generation with advisory prompts, atomic multi-page writes, and session handoff
• Atomic guarantees are provided through SQLite transactions and filesystem-safe write patterns in ai-memory-wiki
• Flexible triggering supports manual invocation, session-end hooks via AI_MEMORY_CONSOLIDATE_ON_SESSION_END, and PreCompact sweeps
• Customization is available through _prompts/consolidation.md files or one-off instructions parameters

Frequently Asked Questions

What happens if no LLM provider is configured?

The consolidation call becomes a no-op and gracefully falls back to rule-based summary generation, ensuring the system remains operational even without LLM connectivity.

How does the advisory prompt system work?

The consolidator automatically loads _prompts/consolidation.md from the target project, sanitizing and capping it at 2,000 characters. You can override this for a single invocation by passing the instructions parameter to memory_consolidate.

Is the wiki storage atomic and safe for concurrent access?

Yes. According to the implementation in crates/ai-memory-wiki/src/wiki.rs, writes use an atomic tmp-plus-rename-fsync pattern wrapped in SQLite transactions, ensuring consistency even during concurrent consolidation operations.

Can I disable multi-page output and generate a single consolidated file?

While multi_page=true is the default, you can control this behavior via the multi_page parameter in the MCP tool call or Rust API, though the standard Karpathy-style workflow favors granular, inter-linked pages for better knowledge organization.

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