How `[auto_improve] require_approval = true` Enables Human-in-the-Loop Review for AI-Memory

When [auto_improve] require_approval is set to true in the AI-Memory configuration, the auto-improvement pipeline stores generated suggestions in a pending state rather than applying them automatically, requiring explicit human approval via the CLI before any changes are committed to the knowledge base.

The akitaonrails/ai-memory repository implements a sophisticated auto-improvement system that can operate in either fully autonomous or human-supervised modes. The require_approval configuration setting—defined as requireapproval in the Rust source—determines whether the system automatically persists AI-generated improvements or queues them for manual review.

Configuration Structure and Type Definition

The approval requirement is defined in the core configuration module as a boolean flag within the AutoImproveConfig struct. According to the source code in crates/ai-memory-core/src/config.rs, the configuration structure uses Figment for TOML deserialization:

use figment::{Figment, providers::{Format, Toml}};

#[derive(Debug, Deserialize)]
pub struct Config {
    pub autoimprove: AutoImproveConfig,
    // other fields omitted
}

#[derive(Debug, Deserialize)]
pub struct AutoImproveConfig {
    pub requireapproval: bool,
    // other fields omitted
}

This field maps to the TOML configuration key [auto_improve] require_approval (snake_case in config files, lowercase requireapproval in the Rust struct). When the system initializes via Config::load(), this value propagates to the AutoImproveImpl constructor, determining the runtime behavior of the improvement loop.

The Approval Gate: Automated vs. Proposal-Only Modes

Setting require_approval = true fundamentally alters the execution flow within AutoImproveImpl::run() in crates/ai-memory-store/src/auto_improve.rs. The trait implementation branches based on this configuration:

Automatic Application (require_approval = false):

• The run() method generates improvements and immediately invokes the wiki writer
• Changes are persisted to the database without intermediate steps
• AutoImproveState tracks only the last_run timestamp

Proposal-Only Mode (require_approval = true):

• Generated diffs are routed to AutoImproveState::pending instead of the wiki writer
• The system sets pending: true in the state object
• No write operations occur on the persistent store until explicit approval is granted

This architectural decoupling ensures that generation and application are separate concerns, allowing operators to review AI-generated edits before they become part of the permanent knowledge graph.

State Management for Pending Approvals

The pending state is tracked in crates/ai-memory-store/src/auto_improve_state.rs, which defines the serializable state object:

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize, Clone, Default)]
pub struct AutoImproveState {
    pub last_run: Option<String>,
    pub pending: bool,
    // Additional fields omitted
}

When operating in approval-required mode, the system maintains this state across scheduling cycles:

1. Schedule Phase: AutoImproveImpl::schedule() initiates the evaluation cycle
2. Generation Phase: Suggestions are created and stored in the pending queue
3. Review Phase: The pending flag remains true until a user approves or rejects the changes
4. Commit Phase: Only upon approval does the system clear the pending flag and apply changes

CLI Integration and Human Review Workflow

The command-line interface provides explicit commands for managing the approval workflow in crates/ai-memory-cli/src/commands/. The system exposes two primary entry points:

The Auto-Improve Command (auto_improve.rs):

use clap::Parser;
use ai_memory_cli::prelude::*;

#[derive(Parser)]
pub struct AutoImproveCmd {
    #[clap(long)]
    pub requireapproval: bool,
    // other flags omitted
}

impl AutoImproveCmd {
    pub async fn run(&self) -> Result<()> {
        let config = Config::load();
        if self.requireapproval {
            // set config flag
        }
        // start auto-improve schedule
        Ok(())
    }
}

The Report Command (auto_improve_report.rs):

use clap::Parser;
use ai_memory_cli::prelude::*;

#[derive(Parser)]
pub struct ReportCmd {
    // flags omitted
}

impl ReportCmd {
    pub async fn run(&self) -> Result<()> {
        // fetch pending auto-improve suggestions and display them
        Ok(())
    }
}

When require_approval is enabled, operators use the report command to inspect queued suggestions before committing them:

# View pending improvements awaiting approval

ai-memory auto-improve report

# Approve specific suggestions (example workflow)

ai-memory auto-improve approve --id <suggestion-id>

Practical Configuration Examples

To enable human-in-the-loop review, set the following in your .ai-memory.toml or equivalent configuration file:

[auto_improve]
require_approval = true

With this setting active, running the improvement cycle produces pending suggestions:

# Generate improvements (stores to pending state only)

ai-memory auto-improve run

# Review before applying

ai-memory auto-improve report

For fully autonomous operation—suitable for development environments or trusted automation—disable the requirement:

[auto_improve]
require_approval = false

Now the scheduler both generates and applies improvements in a single execution:

# Changes are written immediately without user interaction

ai-memory auto-improve run

Summary

• [auto_improve] require_approval = true transforms the auto-improvement system from autonomous to supervised mode
• The requireapproval boolean in crates/ai-memory-core/src/config.rs controls whether AutoImproveImpl::run() applies changes immediately or queues them
• Pending suggestions are tracked via AutoImproveState::pending in crates/ai-memory-store/src/auto_improve_state.rs
• The CLI commands auto_improve and auto_improve_report provide the interface for generation and review workflows
• This setting is essential for production environments where uncontrolled AI edits could corrupt valuable knowledge base data

Frequently Asked Questions

How does require_approval differ from disabling auto-improve entirely?

Disabling auto-improve stops the scheduling and generation phases entirely, while require_approval = true allows the AI to continue generating suggestions—it simply pauses before the commit phase. This enables continuous evaluation of improvement opportunities while maintaining human oversight over the actual modifications to the knowledge base.

Where does the system store suggestions when approval is required?

Pending suggestions are stored within the AutoImproveState struct, specifically tracked by the pending: bool field defined in crates/ai-memory-store/src/auto_improve_state.rs. The actual suggestion data resides in the application's state management layer, accessible via the auto_improve_report CLI command for review.

Can I toggle require_approval without restarting the application?

The configuration is loaded at startup via Config::load() in the CLI command handlers. While the static configuration requires a restart to modify, the CLI accepts a --requireapproval flag in the AutoImproveCmd struct that can override the config file setting for individual command invocations.

What happens if suggestions remain pending for multiple scheduling cycles?

The AutoImproveState tracks both last_run and pending status. If a cycle runs while previous suggestions are still pending, the system typically appends new suggestions to the queue or blocks new generation depending on the specific implementation logic in AutoImproveImpl::run(). Users should review and clear pending states regularly to prevent queue buildup.

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