How the ai-memory Auto-Improvement Scheduler Works: Complete Guide to Configuration and Approval Workflows

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. 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.<rule>) 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/<timestamp>.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

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

[auto_improve.eval]
max_deletions = 10               # Rejects proposals deleting more than 10 pages

These gates are documented in 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:

[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):

ai-memory auto-improve

Target a specific session and stage proposals for later approval:

ai-memory auto-improve --session-id 12345 --stage

Generate a telemetry report for the last 7 days (default), limited to 20 runs:

ai-memory auto-improve-report --limit 20

Inspect pending proposals awaiting manual approval:

cat "$(ai-memory wiki-path)/auto_improve/pending/<timestamp>.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. 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/<timestamp>.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, which specifies how the system recognizes maintenance operations and routes them to the scheduler component.

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