# How ai-memory Manages Auto-Improvement Proposals and Approval > Discover how ai-memory streamlines auto-improvement proposals with a three-stage pipeline for automated application or manual review. Learn about generation, validation, and approval gates. - Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory) - Tags: internals - Published: 2026-08-21 --- **ai-memory converts completed sessions into structured wiki proposals that can be automatically applied or queued for manual review through a three-stage pipeline involving generation, validation, and configurable approval gates.** The **auto-improvement subsystem** in ai-memory transforms observational data from completed sessions into actionable knowledge updates. This system balances automation with safety by staging every proposed change as a reviewable artifact before it reaches the durable wiki store, ensuring that **auto-improvement proposals** maintain full auditability and operator control. ## The Three-Stage Auto-Improvement Pipeline According to the design documentation in [`docs/auto-improvement-loop.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/auto-improvement-loop.md), the auto-improvement workflow consists of three distinct phases that move from raw session data to committed knowledge. ### Proposal Generation from Session Context When a session finishes, the scheduler (or a manual CLI/MCP invocation) reads the session’s observations, recent wiki pages, and additional context to build a prompt. The system invokes an LLM to generate a **proposal** containing a markdown edit (either a create or update operation), supporting evidence, and a computed diff. This proposal is persisted as a pending-review row and written to the hidden path `_pending/auto-improve/` within the wiki structure. This generation step captures the semantic changes implied by user interactions while maintaining isolation from the live wiki until validation completes. ### Staging and Validation with Eval Gates Before any proposal affects the live wiki, the system runs a validation check against path constraints, document kind restrictions, and size limits. If the `[auto_improve.eval]` configuration option is enabled, the proposal enters an **eval gate** where a user-supplied command receives the proposal JSON and must return a pass/fail determination. Failures at this gate cause the individual proposal to be rejected while allowing the remainder of the batch to continue processing. This design prevents low-quality or out-of-policy suggestions from reaching the approval stage without halting the entire improvement loop. ### The Approval Path: Auto-Approval vs. Manual Review The system supports two distinct approval modes controlled by the `auto_improve.require_approval` configuration setting: - **Auto-approval (default):** Validated proposals are immediately applied through `Wiki::apply_batch`, which executes the markdown mutations against the live wiki. Each operation is recorded in the audit trail with full provenance metadata, ensuring that automatically applied changes remain traceable to their source sessions. - **Manual approval:** When `auto_improve.require_approval` is set to `true`, the scheduler and manual runs leave proposals in the pending queue. Human operators can then manage these items through admin APIs. The writer crate in [`crates/ai-memory-store/src/writer.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/writer.rs) implements three key management functions: - `approve_auto_improve_proposal` – Applies the proposal via the standard wiki mutation pipeline - `reject_auto_improve_proposal` – Removes the proposal from the queue with a rejection reason - `fail_auto_improve_proposal` – Marks the proposal as failed, distinct from rejection, typically used for system-level errors These endpoints update the proposal state atomically, ensuring that only approved items invoke `Wiki::apply_batch`. ## Implementation Details in the Source Code The approval logic resides primarily in [`crates/ai-memory-store/src/writer.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/writer.rs) between lines 1531 and 1593, where the state transitions for pending proposals are managed. The actual application of approved proposals occurs in [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs) (lines 1078–1157), which handles the side-car markdown persistence and the final wiki mutations. The design rationale for separating proposals from durable wiki pages appears in [`docs/design-decisions.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/design-decisions.md) (lines 171–179), explaining how this architecture prevents partial or corrupted updates from affecting the knowledge base during the review window. ## CLI Commands for Managing Proposals The ai-memory CLI exposes the full proposal lifecycle through intuitive commands: ```bash # Run auto-improvement review for the newest completed session ai-memory auto-improve # Target a specific session without waiting for the scheduler ai-memory auto-improve --session-id sess-12345 # List all pending proposals in a workspace/project ai-memory pending-writes list --workspace my_ws --project my_proj # Approve a pending proposal (requires admin privileges) ai-memory pending-writes approve # Reject a proposal with documented reasoning ai-memory pending-writes reject --reason "Insufficient evidence" ``` These same operations are available via MCP/HTTP endpoints, allowing the `approve_auto_improve_proposal` function to accept JSON payloads containing the proposal ID and optional audit notes for programmatic integration. ## Configuration Options for Approval Workflows Two critical configuration settings govern the safety characteristics of the auto-improvement system: 1. **`auto_improve.require_approval`** – Controls whether proposals auto-commit or await human review. Defaults to `false` for fully automated learning loops, but should be set to `true` in sensitive environments where human validation is mandatory. 2. **`auto_improve.eval`** – Enables the optional eval gate for custom validation logic. When active, external scripts or services can enforce organizational policies (such as content classification or semantic consistency checks) before proposals reach the approval queue. Both settings respect the same admission webhooks and authentication checks as standard wiki edits, ensuring that automated proposals do not bypass security controls. ## Summary - **ai-memory** generates **auto-improvement proposals** by converting session observations into structured wiki edits with diffs and evidence, stored under `_pending/auto-improve/`. - The **eval gate** provides an optional validation hook that can reject individual proposals without stopping the batch processing pipeline. - Proposals follow one of two **approval paths**: automatic application via `Wiki::apply_batch` (default), or manual review through `approve_auto_improve_proposal`, `reject_auto_improve_proposal`, and `fail_auto_improve_proposal` endpoints. - Source code in [`crates/ai-memory-store/src/writer.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/writer.rs) and [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs) implements the state management and mutation logic, while [`docs/auto-improvement-loop.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/auto-improvement-loop.md) documents the architectural flow. ## Frequently Asked Questions ### How does ai-memory ensure auto-improvement proposals are safe to apply? Every proposal passes through validation checks for path safety, size limits, and document kind constraints before reaching the approval stage. Additionally, the optional `[auto_improve.eval]` gate allows custom security policies to inspect proposal content via external commands. Approved changes are applied through the same `Wiki::apply_batch` pipeline used for human edits, ensuring they respect identical admission webhooks and audit requirements. ### Can I disable automatic approval and require human review for all proposals? Yes. Set `auto_improve.require_approval = true` in your configuration file. This forces both the scheduler and manual CLI runs to leave proposals in the pending queue rather than auto-applying them. Operators can then review, approve, or reject each proposal individually using the `ai-memory pending-writes` commands or the corresponding MCP/HTTP admin APIs. ### What happens when the eval gate rejects a proposal? When the eval gate returns a failure status for a specific proposal, that individual proposal is removed from the batch and logged as rejected, but processing continues for the remaining proposals in the session. This granular failure mode prevents a single problematic suggestion from blocking the entire auto-improvement run, as implemented in the validation logic described in [`docs/auto-improvement-loop.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/auto-improvement-loop.md). ### Where are pending proposals stored before approval? Pending proposals are written to the hidden wiki path `_pending/auto-improve/` as side-car markdown files with associated metadata rows. This staging area keeps proposed changes isolated from the live wiki namespace until they pass validation and receive explicit approval through the functions defined in [`crates/ai-memory-store/src/writer.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/writer.rs) (lines 1581–1589).