# How to Use memory_consolidate for Karpathy-Style LLM Wiki Compilation

> Learn to use memory_consolidate for Karpathy-style LLM wiki compilation. This tool compiles session observations into a structured markdown wiki, following Andrej Karpathy's LLM Wiki pattern.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: how-to-guide
- Published: 2026-08-27

---

**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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/_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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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:

```rust
// 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:

```bash

# 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:

```json
{
  "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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/types.rs)**: Contains `build_batch_request` for converting observations into LLM prompts
- **[`crates/ai-memory-consolidate/src/consolidator.rs`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/admission.rs)**: Defines the `Consolidate` admission operation and HTTP header mappings
- **[`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/_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`](https://github.com/akitaonrails/ai-memory/blob/main/_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`](https://github.com/akitaonrails/ai-memory/blob/main/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.