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

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): Parses the --session argument and constructs the HTTP request to the MCP server.
• MCP HTTP Handler (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): Executes the consolidate_session() function, which runs the LLM using the prompt defined in crates/ai-memory-consolidate/prompts/single_consolidate_system.md.
• Wiki Writer (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:

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:

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

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:

{
  "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:

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.

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, which validates the request and invokes consolidate_session() from crates/ai-memory-consolidate/src/lib.rs.
• The engine uses the LLM prompt defined in 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, 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, 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 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 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.

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