# Memory Consolidate vs Memory Auto-Improve in ai-memory: Key Differences Explained

> Understand memory consolidate vs memory auto-improve in ai-memory. Discover how consolidate updates session narratives and auto-improve builds reusable knowledge for your project wiki.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: deep-dive
- Published: 2026-08-25

---

**Memory consolidate transforms a single session's raw observations into an updated episodic narrative, while memory auto-improve extracts durable, reusable knowledge from multiple completed sessions to populate the project wiki.**

The `ai-memory` repository provides two distinct LLM-powered subsystems for knowledge management. While both leverage the consolidator infrastructure found in `crates/ai-memory-consolidate`, they operate at different stages of the knowledge lifecycle and produce fundamentally different outputs. Understanding when to use **memory consolidate** versus **memory auto-improve** ensures your project documentation remains both immediately accurate and progressively richer over time.

## Core Purpose and Workflow Scope

The primary distinction lies in what each system produces and when it runs.

### Memory Consolidate: Episodic Session Documentation

**Memory consolidate** focuses on a *single session*, converting its raw observation log into a refreshed, semantically-tagged narrative. In [`crates/ai-memory-consolidate/src/consolidator.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/consolidator.rs), the `Consolidator::consolidate_session` method processes the session ID, observation log, and existing page content to generate an updated `sessions/<id>.md` file. This operation is **episodic**—it captures what happened during that specific work session.

### Memory Auto-Improve: Semantic Knowledge Extraction

**Memory auto-improve** operates across *multiple completed sessions* to identify recurring patterns, decisions, and lessons. According to [`docs/auto-improvement-loop.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/auto-improvement-loop.md), this system runs a review process that produces a `ConsolidatedBatch` containing up to five proposed page updates (gotchas, decisions, concepts, procedures, or rules). These proposals are staged as durable **semantic** knowledge under `_pending/auto-improve/` and, once approved, become permanent wiki entries.

## Trigger Mechanisms and Execution Timing

### Explicit vs. Scheduled Execution

- **Memory consolidate** runs **once per session** when explicitly invoked. Users trigger it via the CLI command `ai-memory consolidate …` or through the MCP tool `memory_consolidate`. It executes immediately upon request.

- **Memory auto-improve** operates on a **background scheduler** when an LLM provider is configured, or manually via `ai-memory auto-improve …`. It continuously reviews recent sessions over time rather than processing a single event.

## Input Parameters and LLM Prompts

Both systems use different prompt strategies tailored to their distinct goals.

### Single-Page Prompting

The consolidator uses a single-page prompt defined in [`consolidator.rs`](https://github.com/akitaonrails/ai-memory/blob/main/consolidator.rs) that feeds the session ID, full observation log, current session page body, and optional project-level instructions. This focused context allows the LLM to refine the narrative without structural changes.

### Batch Review Prompting

Auto-improve employs `build_batch_request_with_slots` to construct a review prompt that examines recent observations alongside existing wiki pages. This comparative context enables the LLM to identify gaps between current knowledge and observed patterns, producing structured proposals for new pages.

## Output Destinations and Page Types

The physical locations and formats of generated content differ significantly.

### Direct Session Page Updates

Memory consolidate writes exactly **one** file via `Wiki::write_page` at `sessions/<id>.md`. The change commits immediately to git history and reflects the cleaned-up episodic record.

### Staged Multi-Page Proposals

Memory auto-improve generates **multiple** proposed pages across different namespaces (`gotchas/…`, `decisions/…`, `_rules/…`). These land in `_pending/auto-improve/` as staged proposals. The system creates an audit trail attributing the change to the `auto_improve` actor, leaving the active session untouched until manual or automatic approval applies the changes.

## Safety Checks and Validation Logic

Each system implements different safety boundaries appropriate to its scope.

### Pre-Flight Admission

Memory consolidate performs `AdmissionOp::Consolidate` validation before the LLM call, targeting only the specific session page.

### Multi-Stage Validation

Memory auto-improve validates the anchor session (`sessions/<id>.md`) before processing, then validates each proposed update against path prefixes, tier requirements, page kinds, size limits, and slot invariants. Invalid proposals are rejected before staging, preventing pollution of the wiki namespace.

## Configuration and Customization

### Runtime Parameters

For memory consolidate, developers can tweak prompt limits per-call using `with_prompt_limits`, allowing flexibility for particularly large or complex sessions.

### Scheduler Configuration

Memory auto-improve behavior is controlled by the `[auto_improve]` configuration section, which specifies `require_approval` settings, scheduler intervals, and confidence thresholds as detailed in [`docs/auto-improvement-loop.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/auto-improvement-loop.md).

## Practical Implementation Examples

The following Rust examples demonstrate the distinct API patterns for each system.

### Running Memory Consolidate

```rust
// Example: Consolidating a single session (memory_consolidate)
let consolidator = Consolidator::new(reader, writer, wiki, llm, ws_id, proj_id);
let outcome = consolidator
    .consolidate_session(
        session_id,
        /*dry_run=*/ false,
        actor_ctx,
        /*author_id=*/ None,
        /*instructions=*/ None,
    )
    .await?;
println!("Session page written to {}", outcome.path);

```

### Running Memory Auto-Improve

```rust
// Example: Running the auto-improve reviewer manually (memory_auto_improve)
let reviewer = AutoImproveReviewer::new(reader, writer, wiki, llm, ws_id, proj_id);
let run = reviewer.review_recent_sessions(/*max_sessions=*/ 10).await?;
for proposal in run.proposals {
    println!("Proposed {} → {}", proposal.kind, proposal.path);
    // Proposals are staged under `_pending/auto-improve/` and can be approved later.
}

```

## Summary

- **Memory consolidate** updates *episodic* records by refreshing a single session’s narrative page immediately after the session concludes.
- **Memory auto-improve** extracts *semantic* knowledge from multiple sessions, creating durable wiki pages that capture reusable rules, decisions, and gotchas.
- **Consolidate** runs explicitly on demand via `ai-memory consolidate`; **auto-improve** runs continuously via scheduler or manually via `ai-memory auto-improve`.
- **Consolidate** writes directly to `sessions/<id>.md`; **auto-improve** stages proposals in `_pending/auto-improve/` for approval.
- Both use the infrastructure in [`crates/ai-memory-consolidate/src/consolidator.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/consolidator.rs) but employ different prompts, validation logic, and output strategies.

## Frequently Asked Questions

### When should I use memory consolidate versus allowing auto-improve to handle everything?

Use **memory consolidate** immediately after finishing a work session to ensure the episodic record accurately reflects what occurred. Rely on **memory auto-improve** for long-term knowledge management—it identifies patterns across dozens of sessions that humans might miss, but it does not replace the immediate need for a clean session narrative.

### Does memory auto-improve modify existing session pages?

No. Memory auto-improve specifically avoids mutating active session pages or their git history. It only creates new pages under namespaces like `gotchas/` or `decisions/`, leaving the original `sessions/<id>.md` files intact and creating a separate audit trail for the proposed changes.

### Can I run memory consolidate on a session that has already been processed?

Yes. The `Consolidator::consolidate_session` method is idempotent in practice—you can re-run consolidation with updated instructions or after adding new observations. Each run regenerates the session page based on the complete current observation log and existing page content.

### What happens if the auto-improve reviewer generates invalid proposals?

The validation layer in the auto-improve workflow checks each proposed update against strict invariants including path prefixes, tier assignments, and slot requirements. Invalid proposals are rejected before reaching the `_pending/auto-improve/` directory, ensuring only structurally valid pages enter the approval workflow.