# How the ai-memory Auto-Improvement Scheduler Works: Complete Guide to Configuration and Approval Workflows > Discover how the ai-memory auto-improvement scheduler works. Learn to configure approval workflows for wiki edits with this complete guide. Streamline your AI's knowledge base. - Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory) - Tags: deep-dive - Published: 2026-08-20 --- **The ai-memory auto-improvement scheduler is a background server component that periodically reviews completed sessions and proposes durable wiki edits; administrators configure approval workflows via the `[auto_improve]` TOML section to require manual review or enable auto-approval.** The **auto-improvement scheduler** in the `akitaonrails/ai-memory` repository automates the extraction of durable knowledge from ephemeral LLM sessions. By continuously scanning completed sessions and transforming insights into structured wiki updates, the system reduces manual documentation overhead while maintaining governance through configurable approval gates. ## What Is the ai-memory Auto-Improvement Scheduler? The **auto-improvement scheduler** operates as a store-wide background process integrated with the "scheduled consolidation queue" described in [`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/ARCHITECTURE.md). When an LLM provider is configured, the scheduler monitors every project for newly completed sessions that lack a persisted auto-improvement run. It orchestrates a multi-stage pipeline that converts session observations into structured wiki proposals, applying either immediate execution or human-in-the-loop review based on your governance policies. ## How the Auto-Improvement Scheduler Works The scheduler follows a deterministic seven-step lifecycle for each eligible session: ### 1. Eligibility and Scheduling Every completed session becomes eligible once an LLM provider is active. The scheduler selects the newest completed session that has **no persisted auto-improvement run**, skipping any sessions already processed. This mechanism prevents duplicate processing while ensuring the system prioritizes recent learnings. ### 2. Pre-flight Validation Checks Before invoking the LLM, the scheduler performs mandatory validation: - **Pinned Page Protection**: Sessions marked as *pinned* are immutable and skipped immediately. - **SessionEnd Verification**: The session’s `SessionEnd` page must exist and pass retention/curation filters. - **Provider Health**: The configured LLM provider must be reachable. If any check fails, the run is recorded as a **pre-flight skip**, allowing the scheduler to advance to the next session on its subsequent tick. ### 3. LLM Review and Proposal Generation Upon passing validation, the LLM receives the session’s observations and generates **proposals**—structured instructions for wiki modifications. Each proposal includes: - **Target page path**: The destination within the wiki hierarchy. - **Kind classification**: Such as `procedure`, `decision`, or `knowledge`. - **Structured diff**: A machine-readable description of the proposed change (creations, updates, or deletions). ### 4. Structural Validation and Safety Gates Proposals undergo structural validation to enforce wiki integrity: - Path syntax must be legal and within allowed namespaces. - Kind values must match the approved taxonomy. - **Pinned page protection**: No edits may target immutable pinned pages. - Optional evaluation gates (configured via `auto_improve.eval.`) can reject high-impact proposals, such as bulk deletions exceeding defined thresholds. ### 5. Approval Path Execution The scheduler routes validated proposals based on the `require_approval` configuration: - **Auto-approval** (`require_approval = false`): Validated proposals are written directly to the wiki immediately. - **Manual approval** (`require_approval = true`): Proposals are stored as **pending-writes**, and a dedicated approval page is generated at `auto_improve/pending/.md` for administrator review. ### 6. Telemetry and Audit Logging Each run generates telemetry capturing the outcome, proposal count, and success or failure status. Access this data programmatically via the CLI using `ai-memory auto-improve-report`, or stage telemetry pages for long-term audit trails using the `--stage` flag. ## Configuring the Approval Workflow Governance policies are defined in the `[auto_improve]` section of your ai-memory TOML configuration file (typically located at `~/.config/ai-memory.toml` or as specified in your environment). ### TOML Configuration Settings ```toml [auto_improve] require_approval = true # Forces manual review; default is false scheduler.enabled = true # Activates background processing; default is true ``` Changing these values requires a restart of the `ai-memory` process to reload the configuration. ### Evaluation Gates for High-Impact Changes Advanced operators can implement safety rails using evaluation rules: ```toml [auto_improve.eval] max_deletions = 10 # Rejects proposals deleting more than 10 pages ``` These gates are documented in [`docs/auto-improve-eval-gates.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/auto-improve-eval-gates.md) and provide automated filtering before proposals reach the approval queue. ### Disabling the Scheduler For maintenance windows or batch processing periods, disable the background scheduler without uninstalling the feature: ```toml [auto_improve.scheduler] enabled = false ``` When disabled, the system stops automatic scheduling but retains all historical proposal data and pending writes. ## CLI Commands for Manual Control and Telemetry While the scheduler operates automatically, operators retain fine-grained control via the CLI: Run a manual review for the newest eligible session (respects current `require_approval` settings): ```bash ai-memory auto-improve ``` Target a specific session and stage proposals for later approval: ```bash ai-memory auto-improve --session-id 12345 --stage ``` Generate a telemetry report for the last 7 days (default), limited to 20 runs: ```bash ai-memory auto-improve-report --limit 20 ``` Inspect pending proposals awaiting manual approval: ```bash cat "$(ai-memory wiki-path)/auto_improve/pending/.md" ``` ## Summary - The **ai-memory auto-improvement scheduler** runs as a background process in the store-wide consolidation queue, automatically identifying completed sessions for knowledge extraction. - **Pre-flight checks** enforce immutability of pinned pages, validate `SessionEnd` existence, and verify LLM provider connectivity before processing. - Proposals include structured diffs with target paths and kind classifications, validated against path legality and governance rules before persistence. - Configure approval workflows via **`[auto_improve]` TOML settings**: set `require_approval = true` to enable manual review queues, or `scheduler.enabled = false` to pause automation. - Use **`ai-memory auto-improve`** for manual invocation and **`ai-memory auto-improve-report`** to audit telemetry and proposal outcomes. ## Frequently Asked Questions ### How does the scheduler determine which sessions to process? The scheduler selects the newest completed session that has **no persisted auto-improvement run**, as implemented in the store-wide scheduled consolidation queue described in [`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/ARCHITECTURE.md). If a session already has a recorded run, it is automatically skipped to prevent duplicate processing. ### What happens if I enable `require_approval` but don't review pending proposals? Proposals remain stored as **pending-writes** in `auto_improve/pending/.md` indefinitely until an administrator manually applies or discards them. The scheduler continues processing new sessions, but unapproved proposals will not modify the wiki until explicitly actioned. ### Can I prevent the scheduler from deleting sensitive wiki pages? Yes. Enable the **`auto_improve.eval`** gates in your TOML configuration to set thresholds (such as `max_deletions`) that reject high-impact proposals. Additionally, mark critical pages as **pinned**; the pre-flight checks automatically skip any sessions attempting to modify pinned content. ### Where is the skill definition that triggers auto-improvement implemented? The semantic intent routing that triggers auto-improvement is defined in [`crates/ai-memory-core/src/routing_skills/ai-memory-learning-maintenance/SKILL.md`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-core/src/routing_skills/ai-memory-learning-maintenance/SKILL.md), which specifies how the system recognizes maintenance operations and routes them to the scheduler component.