# How to Force Consolidation of a Specific Session in ai-memory

> Force consolidation of a specific ai-memory session using the CLI command ai-memory consolidate --session <SESSION_ID>. Trigger the LLM pipeline to convert logs into a markdown wiki.

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

---

**You can force consolidation of a specific session in ai-memory by running the `ai-memory consolidate --session <SESSION_ID>` CLI command, which immediately triggers the LLM-driven pipeline that converts raw observation logs into a searchable markdown wiki page.**

The `akitaonrails/ai-memory` project continuously accumulates raw observation logs for every coding-agent session, and understanding how to force a consolidation of a specific session allows you to generate durable documentation on demand rather than waiting for automatic background scheduling. This manual intervention is essential when you need immediate searchability or wish to archive a session's progress before the default timer or close-event triggers.

## Understanding the Consolidation Architecture

The consolidation pipeline in ai-memory follows a strict multi-layer architecture that ensures atomic writes and proper indexing. When you request a manual consolidation, the request flows through four primary Rust components that handle authentication, LLM processing, and wiki generation.

- **CLI Front-End** ([`crates/ai-memory-cli/src/commands/consolidate.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/consolidate.rs)): Parses the `--session` argument and constructs the HTTP request to the MCP server.
- **MCP HTTP Handler** ([`crates/ai-memory-mcp/src/handlers/consolidate.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/handlers/consolidate.rs)): Exposes the `POST /api/v1/sessions/<session_id>/consolidate` endpoint, validates the session identifier, and forwards the request to the consolidation engine.
- **Consolidation Engine** ([`crates/ai-memory-consolidate/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/lib.rs)): Executes the `consolidate_session()` function, which runs the LLM using the prompt defined in [`crates/ai-memory-consolidate/prompts/single_consolidate_system.md`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/prompts/single_consolidate_system.md).
- **Wiki Writer** ([`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs)): Performs atomic file operations via `Wiki::write_page()` to store the resulting markdown and notify the full-text search indexer.

## How to Force Consolidation of a Specific Session

You have three primary methods to trigger immediate consolidation depending on your environment and integration needs.

### Using the CLI (Most Common)

Run the following command, replacing the placeholder with your actual session UUID:

```bash
ai-memory consolidate --session 3f9a2b1c-e4d7-4a8b-9f01-c3e5f6d7a9b2

```

This command sends a `POST` request to the MCP server and prints a summary upon completion. You will see output similar to:

```text
✅ Consolidated session 3f9a2b1c-e4d7-4a8b-9f01-c3e5f6d7a9b2 → pages/sessions/3f9a2b1c-e4d7-4a8b-9f01-c3e5f6d7a9b2.md

```

### Using the HTTP API Directly

For scripting or external agent integration, call the endpoint directly with `curl`:

```bash
curl -X POST \
  -H "Authorization: Bearer $AI_MEMORY_AUTH_TOKEN" \
  "http://127.0.0.1:49374/api/v1/sessions/3f9a2b1c-e4d7-4a8b-9f01-c3e5f6d7a9b2/consolidate"

```

The server returns a JSON response containing the generated page metadata:

```json
{
  "title":"Session 3f9a2b1c-e4d7-4a8b-9f01-c3e5f6d7a9b2",
  "summary":"Agent finished a refactor of the request-handler module",
  "page_path":"pages/sessions/3f9a2b1c-e4d7-4a8b-9f01-c3e5f6d7a9b2.md"
}

```

### Programmatically from Rust

If you are building a Rust tool that integrates with ai-memory, use the client library to trigger consolidation:

```rust
use ai_memory_mcp::client::AiMemoryClient;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = AiMemoryClient::new("http://127.0.0.1:49374")?;
    let session_id = "3f9a2b1c-e4d7-4a8b-9f01-c3e5f6d7a9b2";
    
    let result = client.consolidate_session(session_id).await?;
    println!("Consolidated → {}", result.page_path);
    
    Ok(())
}

```

This method invokes `AiMemoryClient::consolidate_session()`, which is a thin wrapper around the same MCP endpoint used by the CLI, returning a `ConsolidatedPage` struct defined in [`ai-memory-consolidate/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/ai-memory-consolidate/src/lib.rs).

## How the Consolidation Engine Processes Sessions

When you force a consolidation, the engine bypasses the background scheduler and immediately processes the session's observation log. The `consolidate_session()` function loads the raw log entries, applies the **single-consolidate** system prompt to structure the content, and writes the output atomically to the wiki directory. This atomic write—implemented as a temporary file creation followed by a rename operation in `Wiki::write_page()`—ensures that the full-text search index never indexes partially written files or encounters corruption during the write process.

## Summary

- Execute `ai-memory consolidate --session <SESSION_ID>` to immediately force consolidation of any specific session without waiting for the background timer.
- The CLI communicates with the MCP handler at [`crates/ai-memory-mcp/src/handlers/consolidate.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/handlers/consolidate.rs), which validates the request and invokes `consolidate_session()` from [`crates/ai-memory-consolidate/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/lib.rs).
- The engine uses the LLM prompt defined in [`crates/ai-memory-consolidate/prompts/single_consolidate_system.md`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/prompts/single_consolidate_system.md) to generate structured markdown.
- Final output is written atomically via `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), ensuring the page is immediately searchable in the wiki graph.

## Frequently Asked Questions

### What is the difference between automatic and forced consolidation in ai-memory?

Automatic consolidation runs on a background timer or when a session closes, whereas forced consolidation happens immediately when you invoke the CLI command or HTTP endpoint. Both paths use the identical `consolidate_session()` logic in [`crates/ai-memory-consolidate/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/lib.rs), but forced consolidation allows you to generate searchable documentation while a session is still active or before the scheduled interval expires.

### Can I force consolidation for a session that is still recording observations?

Yes, you can force consolidation at any time, even while the session is active. The consolidation engine reads the current state of the observation log up to that point and generates a markdown snapshot. Subsequent forced consolidations will overwrite the previous wiki page with the updated content, allowing you to create progressive checkpoints of a long-running session.

### Where are the consolidated session pages stored in the file system?

The consolidated markdown pages are written to the wiki directory, typically under `pages/sessions/<session_id>.md`, as returned in the `page_path` field of the JSON response. The `Wiki::write_page()` function in [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs) handles these paths automatically and ensures proper wikilink integration into the broader ai-memory graph.

### Is authentication required to force consolidation via the HTTP API?

Yes, the MCP HTTP handler at [`crates/ai-memory-mcp/src/handlers/consolidate.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/handlers/consolidate.rs) requires a valid bearer token passed in the `Authorization` header for all consolidation requests. This security boundary ensures that only authorized clients can trigger LLM processing and write operations to the wiki storage.