Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat: schedule auto-improvement reviews
AkitaOnRails4e96a3407f77
diff --git a/AGENTS.md b/AGENTS.mdindex b7349e89..09626784 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -42,7 +42,7 @@ match the intent to the tool. They do not need to name the tool.| "save context for the next session" / wrapping up / ending this session | `memory_handoff_begin` (session-end only; do **not** use for status/briefing; single-use handoff; terse summary; put detail in `open_questions` + `next_steps` bullets; pass `workspace` + `project` together only for a named sibling workspace/project) || "discard that handoff" / "I created a handoff by mistake" | `memory_handoff_cancel` (requires exact `handoff_id` from `memory_handoff_begin`; marks it expired before the next session sees it) || "consolidate this session" / "compile what we learned" (also runs on PreCompact; at session end only if `AI_MEMORY_CONSOLIDATE_ON_SESSION_END` is set) | `memory_consolidate` |-| "what did we learn from this session?" / "what memory should we add?" / explicit wrap-up learning review | `memory_auto_improve` (reviews a completed session and applies validated wiki edits through the auto-improvement approval path; omit `session_id` for latest completed session) |+| "what did we learn from this session?" / "what memory should we add?" / explicit wrap-up learning review | `memory_auto_improve` (manual learning review for a completed session; omit `session_id` for latest completed session; the server also schedules background review for newly completed sessions when configured) || "remember this permanently" / "save a note" / "add an annotation" / durable project knowledge | `memory_write_page` (write a wiki page; do **not** use handoff for permanent notes; put the title as a `# H1` on the first line of `body` and omit the `title` arg — ai-memory derives it from the H1) || "read the page about X" / "show me the full content of Y" / "open the page on Z" | `memory_read_page` (full body; pass a query to search or `path` for a direct lookup; pass `workspace` + `project` together only for a named sibling workspace/project) || "delete the page X" / "remove that note" | `memory_delete_page` (by exact `path`; idempotent; pass `workspace` + `project` together only for a named sibling workspace/project) |@@ -96,11 +96,14 @@ query specific error/subsystem terms before designing a fix.### Learning Review-`memory_auto_improve` is a learning reviewer that applies validated wiki edits-through the auto-improvement approval path. Use it when the user asks what-durable lessons this session suggests, or at explicit wrap-up when reviewing-proposed memory would be useful. Admins can opt into manual review with-`[auto_improve] require_approval = true`, in which case proposals stay in+The server schedules background auto-improvement for newly completed sessions+when an LLM provider is configured. `memory_auto_improve` is the manual version:+use it when the user asks what durable lessons this session suggests, or at+explicit wrap-up when reviewing proposed memory would be useful. Scheduled and+manual runs apply or stage validated edits through the auto-improvement approval+path. Admins can turn off scheduling with `[auto_improve.scheduler] enabled =+false`, or opt into manual proposal approval with `[auto_improve]+require_approval = true`, in which case scheduled and manual proposals stay inpending-writes until approved.### When you write a project rule, write it here@@ -189,8 +192,9 @@ durable retrieval follows the Karpathy-style LLM Wiki pattern.- When a change affects user-visible behavior, installation, supportedplatforms, supported agents, providers, or deployment, update`CHANGELOG.md` and the README/docs support references in the same commit.-- Do not bump crate/package versions or cut release tags automatically after- every merged PR. Ask the user before any version bump or release tag.+- Do not bump crate/package versions, minor versions, or cut release tags+ automatically. Ask the user before any version bump or release tag; prefer no+ version change unless the user explicitly approves it.- When asked to evaluate a PR, report the pros, cons, and recommended fix,then ask the user for approval before merging or pushing PR changes. Do notmerge PRs during evaluation unless the user explicitly approves that action.diff --git a/CHANGELOG.md b/CHANGELOG.mdindex aa2290ec..9da598cf 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Added+- Added a server-side auto-improvement scheduler. When an LLM provider is+ configured, `[auto_improve.scheduler] enabled = true` reviews newly completed+ sessions in the background, stages validated proposals for audit, and then+ follows the normal auto-improvement approval policy.+- Added persistent scheduler state and per-session scheduler claims so upgrades+ from the v1.0.3-era schema do not process historical session backlog+ automatically, and failed scheduled reviews do not retry forever. Manual+ `ai-memory auto-improve --session-id <uuid>` and MCP `memory_auto_improve`+ remain the catch-up path for older or failed scheduled sessions.++### Changed+- Clarified that scheduling and approval are separate: disable automatic review+ with `[auto_improve.scheduler] enabled = false`; keep proposals pending with+ `[auto_improve] require_approval = true`.+## [1.0.10] - 2026-06-15### Changeddiff --git a/README.md b/README.mdindex 2fc7d898..786a4c64 100644--- a/README.md+++ b/README.md@@ -129,17 +129,23 @@ priors are at the [bottom](#influences-and-prior-art).one-shot-summarises them into seed wiki pages. Future sessionsbuild on top.- **"What durable lesson did that session teach?"**- `ai-memory auto-improve --session-id <uuid>` reviews one completed session- with the configured LLM, records proposed wiki edits in the pending-writes- audit trail, and approves them immediately through the normal wiki write path.- Agents can also call `memory_auto_improve` to review the latest completed- session in the current project without knowing the session id. If you want a- human review queue instead, set `[auto_improve] require_approval = true` and- use `pending-writes list`/`show`/`diff`/`approve`/`reject`.-- Existing installs do not need per-project migration. Older configs may still- contain an `[auto_improve] mode = ...` line; current ai-memory ignores that- legacy key, so you can remove it when convenient.+ When an LLM provider is configured, ai-memory runs a background+ auto-improvement scheduler for newly completed sessions. It records proposed+ wiki edits in the pending-writes audit trail, then approves them immediately+ through the normal wiki write path by default. Scheduling and approval are+ separate: set `[auto_improve.scheduler] enabled = false` to stop automatic+ review, or set `[auto_improve] require_approval = true` to keep both scheduled+ and manual proposals pending for human review. `ai-memory auto-improve+ --session-id <uuid>` and MCP `memory_auto_improve` remain available for manual+ catch-up or targeted reruns.++ Existing installs do not need per-project migration. The scheduler initializes+ a per-project first-run watermark so historical sessions are not reviewed+ automatically on upgrade, then records per-session claims so failed scheduled+ reviews do not retry forever; use manual auto-improve for old sessions or+ failed scheduled sessions you want to catch up. Older configs may still contain+ an `[auto_improve] mode = ...` line; current ai-memory ignores that legacy key,+ so you can remove it when convenient.- **"What housekeeping should I consider?"**`ai-memory curator` runs a no-LLM, rule-based maintenance report over coldepisodic pages, stale slots, duplicate exact normalized titles, and dangling@@ -556,7 +562,7 @@ diagram, crate breakdown, schema notes, and invariants.| [`docs/users.md`](docs/users.md) | **Multi-user attribution (v0.8).** Four-rung auth ladder, `ai-memory user add/list/expire/revive/rotate-token` walkthrough, backward-compat migration for pre-v0.8 installs, token storage rationale. || [`docs/https-via-proxy.md`](docs/https-via-proxy.md) | **HTTPS via a reverse proxy.** When you need TLS (multi-user, non-loopback) and when you don't (loopback / stdio). Copy-paste docker compose templates for Caddy + Let's Encrypt, Caddy + internal CA (LAN-only), Cloudflare Tunnel (no open ports), and external cert files; plus native-Caddy + nginx recipes. The "thinking you're secure when you're not" failure modes explicitly called out. || [`docs/lifecycle-ops.md`](docs/lifecycle-ops.md) | **Read before running purge / rename / backup / restore / reset / reindex / restore-page.** Safety matrix for state-touching commands, per-project disk layout (how isolation actually works), checkpoint-based page recovery, and operator workflows for "fresh start", "snapshot before risky op", "drop one project", and rebuilding SQLite from wiki files. |-| [`docs/auto-improvement-loop.md`](docs/auto-improvement-loop.md) | Auto-improvement design notes: Hermes-inspired post-session review, auto-approval default, manual review opt-in, pending proposal storage, and curator work. |+| [`docs/auto-improvement-loop.md`](docs/auto-improvement-loop.md) | Auto-improvement design notes: Hermes-inspired scheduled review, auto-approval default, manual review opt-in, pending proposal storage, and curator work. || [`docs/llm-provider-comparison.md`](docs/llm-provider-comparison.md) | Empirical notes behind the recommended LLM defaults. || [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Operational summary: data flow, crate layout, cross-cutting invariants, schema. || [`docs/design-decisions.md`](docs/design-decisions.md) | The full v1 spec. |diff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rsindex ccef7891..37577f6f 100644--- a/crates/ai-memory-cli/src/commands/serve.rs+++ b/crates/ai-memory-cli/src/commands/serve.rs@@ -5,14 +5,21 @@ use std::path::Path;use std::sync::Arc;use std::time::Duration;-use ai_memory_consolidate::{Consolidator, run_lint, run_sweep};-use ai_memory_core::{ActiveProject, ProjectId, Sanitizer, WorkspaceId};+use ai_memory_consolidate::{+ AutoImproveReviewConfig, Consolidator, run_auto_improve_review, run_lint, run_sweep,+};+use ai_memory_core::{+ ActiveProject, ActorContext, PagePath, ProjectId, Sanitizer, SessionId, WorkspaceId,+};use ai_memory_hooks::{DEFAULT_HOOK_INGEST_MAX_IN_FLIGHT, HookState, ProjectCacheStore, hook_router,};use ai_memory_llm::{Embedder, LlmProvider, ProviderHealth, build_embedder, build_provider};use ai_memory_mcp::{AdminState, AiMemoryServer, admin_router};-use ai_memory_store::{EmbeddingWrite, ReaderPool, Store, WriterHandle, f32_vec_to_bytes};+use ai_memory_store::{+ ApproveAutoImproveProposalResult, AutoImproveProposalOperation, EmbeddingWrite,+ NewAutoImproveProposal, ReaderPool, StageAutoImproveRun, Store, WriterHandle, f32_vec_to_bytes,+};use ai_memory_web;use ai_memory_wiki::{WatcherHandle, Wiki, migrations, run_wiki_migrations};use anyhow::{Context, Result};@@ -34,7 +41,7 @@ use tracing::info;use crate::auth::{AuthState, require_bearer};use crate::cli::{ServeArgs, TransportKind};-use crate::config::{Config, MaintenanceSettings};+use crate::config::{AutoImproveSettings, Config, MaintenanceSettings};/// 10 MB cap on inbound HTTP bodies. The /hook ingress accepts the/// agent's raw payload which can include a tool output excerpt@@ -177,6 +184,7 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {let admin_llm = consolidator_setup.admin_llm;let _maintenance_tasks = start_maintenance_scheduler(config.maintenance.clone(),+ config.auto_improve.clone(),store.reader.clone(),store.writer.clone(),wiki.clone(),@@ -425,6 +433,7 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {#[allow(clippy::too_many_arguments)]fn start_maintenance_scheduler(settings: MaintenanceSettings,+ auto_improve: AutoImproveSettings,reader: ReaderPool,writer: WriterHandle,wiki: Wiki,@@ -434,9 +443,9 @@ fn start_maintenance_scheduler(project_id: ProjectId,decay: ai_memory_store::DecayParams,) -> Vec<tokio::task::JoinHandle<()>> {- if !settings.enabled {- info!("scheduled maintenance disabled");- return Vec::new();+ let maintenance_enabled = settings.enabled;+ if !maintenance_enabled {+ info!("scheduled retention/lint/embed maintenance disabled");}let forget_sweep_interval_secs = settings.forget_sweep_interval_secs;@@ -444,7 +453,7 @@ fn start_maintenance_scheduler(let embedding_backfill_interval_secs = settings.embedding_backfill_interval_secs;let mut tasks = Vec::new();- if forget_sweep_interval_secs > 0 {+ if maintenance_enabled && forget_sweep_interval_secs > 0 {let reader = reader.clone();let writer = writer.clone();tasks.push(tokio::spawn(async move {@@ -463,7 +472,7 @@ fn start_maintenance_scheduler(}));}- if lint_interval_secs > 0 {+ if maintenance_enabled && lint_interval_secs > 0 {let reader = reader.clone();let wiki = wiki.clone();let llm = llm.clone();@@ -492,7 +501,7 @@ fn start_maintenance_scheduler(}));}- if embedding_backfill_interval_secs > 0 {+ if maintenance_enabled && embedding_backfill_interval_secs > 0 {if let Some(embedder) = embedder {let reader = reader.clone();let writer = writer.clone();@@ -525,6 +534,114 @@ fn start_maintenance_scheduler(}}+ let scheduler = auto_improve.scheduler.clone();+ if !scheduler.enabled || scheduler.interval_secs == 0 || scheduler.max_sessions_per_tick == 0 {+ info!("auto-improve scheduler disabled; manual auto-improve remains available");+ } else if let Some(llm) = llm.clone() {+ let reader = reader.clone();+ let writer = writer.clone();+ let wiki = wiki.clone();+ tasks.push(tokio::spawn(async move {+ let interval = std::time::Duration::from_secs(scheduler.interval_secs);+ if let Err(e) = writer+ .ensure_auto_improve_scheduler_state(workspace_id, project_id)+ .await+ {+ tracing::warn!(error = %e, "scheduled auto-improve state init failed");+ }+ loop {+ tokio::time::sleep(interval).await;+ if let Err(e) = writer+ .ensure_auto_improve_scheduler_state(workspace_id, project_id)+ .await+ {+ tracing::warn!(error = %e, "scheduled auto-improve state init failed");+ continue;+ }+ let candidates = match reader+ .auto_improve_candidate_sessions(+ workspace_id,+ project_id,+ scheduler.min_session_age_secs,+ scheduler.max_sessions_per_tick,+ )+ .await+ {+ Ok(candidates) => candidates,+ Err(e) => {+ tracing::warn!(error = %e, "scheduled auto-improve candidate query failed");+ continue;+ }+ };+ if candidates.is_empty() {+ tracing::debug!("scheduled auto-improve found no eligible sessions");+ continue;+ }+ let mut reviewed = 0usize;+ let ctx = ScheduledAutoImproveContext {+ reader: &reader,+ writer: &writer,+ wiki: &wiki,+ llm: &llm,+ workspace_id,+ project_id,+ settings: &auto_improve,+ };+ for candidate in candidates {+ let claimed = match ctx+ .writer+ .claim_auto_improve_scheduler_session(+ ctx.workspace_id,+ ctx.project_id,+ candidate.session_id,+ candidate.ended_at,+ )+ .await+ {+ Ok(claimed) => claimed,+ Err(e) => {+ tracing::warn!(+ session_id = %candidate.session_id,+ error = %e,+ "scheduled auto-improve claim failed"+ );+ continue;+ }+ };+ if !claimed {+ tracing::debug!(+ session_id = %candidate.session_id,+ "scheduled auto-improve candidate already claimed or reviewed"+ );+ continue;+ }+ match run_scheduled_auto_improve(&ctx, candidate.session_id).await {+ Ok(outcome) => {+ reviewed += 1;+ info!(+ session_id = %candidate.session_id,+ run_id = %outcome.run_id,+ proposals = outcome.proposals,+ approved = outcome.approved,+ pending = outcome.pending,+ conflicts = outcome.conflicts,+ "scheduled auto-improve completed"+ );+ }+ Err(e) => tracing::warn!(+ session_id = %candidate.session_id,+ error = %e,+ "scheduled auto-improve failed"+ ),+ }+ }+ info!(reviewed, "scheduled auto-improve tick completed");+ }+ }));+ } else {+ info!("auto-improve scheduler enabled but no LLM provider is configured; job not started");+ }+if tasks.is_empty() {info!("scheduled maintenance enabled but all intervals are disabled");} else {@@ -614,6 +731,161 @@ async fn flush_embedding_batch(}}+struct ScheduledAutoImproveOutcome {+ run_id: ai_memory_core::AutoImproveRunId,+ proposals: usize,+ approved: usize,+ pending: usize,+ conflicts: usize,+}++struct ScheduledAutoImproveContext<'a> {+ reader: &'a ReaderPool,+ writer: &'a WriterHandle,+ wiki: &'a Wiki,+ llm: &'a Arc<dyn LlmProvider>,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ settings: &'a AutoImproveSettings,+}++async fn run_scheduled_auto_improve(+ ctx: &ScheduledAutoImproveContext<'_>,+ session_id: SessionId,+) -> Result<ScheduledAutoImproveOutcome> {+ let cfg = AutoImproveReviewConfig {+ min_observations: ctx.settings.min_observations,+ min_session_duration_secs: ctx.settings.min_session_duration_secs,+ min_confidence: ctx.settings.min_confidence,+ max_input_tokens: ctx.settings.max_input_tokens,+ max_proposals_per_run: ctx.settings.max_proposals_per_run,+ include_raw_fallback: ctx.settings.include_raw_fallback,+ proposal_actor: ctx.settings.proposal_actor.clone(),+ pending_path: ctx.settings.pending_path.clone(),+ };+ let report = run_auto_improve_review(+ ctx.reader,+ &**ctx.llm,+ ctx.workspace_id,+ ctx.project_id,+ session_id,+ cfg.clone(),+ )+ .await?;+ let proposals =+ scheduled_auto_improve_new_proposals(ctx.reader, ctx.workspace_id, ctx.project_id, &report)+ .await?;+ let staged = ctx+ .writer+ .stage_auto_improve_run(StageAutoImproveRun {+ workspace_id: ctx.workspace_id,+ project_id: ctx.project_id,+ session_id: Some(session_id),+ provider: Some(report.provider.clone()),+ model: Some(report.model.clone()),+ summary: Some(report.summary.clone()),+ warnings_json: serde_json::to_value(&report.warnings)+ .unwrap_or_else(|_| serde_json::json!([])),+ rejected_candidates_json: serde_json::to_value(&report.rejected_candidates)+ .unwrap_or_else(|_| serde_json::json!([])),+ config_json: serde_json::json!({+ "trigger": "scheduler",+ "min_observations": cfg.min_observations,+ "min_session_duration_secs": cfg.min_session_duration_secs,+ "min_confidence": cfg.min_confidence,+ "max_input_tokens": cfg.max_input_tokens,+ "max_proposals_per_run": cfg.max_proposals_per_run,+ "include_raw_fallback": cfg.include_raw_fallback,+ "require_approval": ctx.settings.require_approval,+ }),+ proposal_actor: ActorContext {+ agent: Some(cfg.proposal_actor.clone()),+ ..ActorContext::default()+ },+ proposals,+ })+ .await?;++ for id in &staged.proposal_ids {+ ctx.wiki+ .write_auto_improve_sidecar(ctx.workspace_id, ctx.project_id, *id)+ .await?;+ }++ let mut approved = 0usize;+ let mut pending = 0usize;+ let mut conflicts = 0usize;+ for proposal_id in &staged.proposal_ids {+ if ctx.settings.require_approval {+ pending += 1;+ continue;+ }+ match ctx+ .wiki+ .approve_auto_improve_proposal(+ ctx.workspace_id,+ ctx.project_id,+ *proposal_id,+ ActorContext {+ agent: Some("auto_improve_scheduler_auto_approve".into()),+ ..ActorContext::default()+ },+ None,+ Some(ai_memory_wiki::AdmissionContext {+ op: ai_memory_wiki::AdmissionOp::WritePage,+ ..ai_memory_wiki::AdmissionContext::default()+ }),+ )+ .await?+ {+ ApproveAutoImproveProposalResult::Approved { .. } => approved += 1,+ ApproveAutoImproveProposalResult::Conflict => conflicts += 1,+ }+ }++ Ok(ScheduledAutoImproveOutcome {+ run_id: staged.run_id,+ proposals: staged.proposal_ids.len(),+ approved,+ pending,+ conflicts,+ })+}++async fn scheduled_auto_improve_new_proposals(+ reader: &ReaderPool,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ report: &ai_memory_consolidate::AutoImproveReport,+) -> Result<Vec<NewAutoImproveProposal>> {+ let mut proposals = Vec::with_capacity(report.proposals.len());+ for p in &report.proposals {+ let path = PagePath::new(p.path.clone())?;+ let operation = if reader+ .page_body_by_ids(workspace_id, project_id, path.as_str())+ .await?+ .is_some()+ {+ AutoImproveProposalOperation::Update+ } else {+ AutoImproveProposalOperation::Create+ };+ proposals.push(NewAutoImproveProposal {+ operation,+ target_path: path,+ kind: p.kind.clone(),+ title: p.title.clone(),+ confidence: f64::from(p.confidence),+ rationale: p.rationale.clone(),+ evidence_json: serde_json::to_value(&p.evidence)+ .unwrap_or_else(|_| serde_json::json!([])),+ body_markdown: p.body_markdown.clone(),+ artifact_sha256: None,+ });+ }+ Ok(proposals)+}+async fn configure_embedder(config: &Config,store: &Store,diff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rsindex 19093855..3cbbf4a9 100644--- a/crates/ai-memory-cli/src/config.rs+++ b/crates/ai-memory-cli/src/config.rs@@ -105,9 +105,10 @@ pub struct Config {pub decay: ai_memory_store::DecayParams,/// Server-side scheduled maintenance. Jobs run outside hook latency.pub maintenance: MaintenanceSettings,- /// Optional auto-improvement reviewer. Manual CLI/admin runs approve- /// validated proposals by default unless `require_approval` is set; the- /// SessionEnd trigger stays off by default.+ /// Auto-improvement reviewer. The scheduler launches background review for+ /// newly completed sessions; manual CLI/admin/MCP runs remain available.+ /// Both approve validated proposals by default unless `require_approval` is+ /// set. The SessionEnd trigger stays off by default.pub auto_improve: AutoImproveSettings,/// Privacy-strip tuning. Built-in patterns always run; this section/// lets the operator extend or punch holes in them.@@ -366,6 +367,9 @@ impl Default for Config {#[derive(Debug, Clone, Serialize, Deserialize)]#[serde(default)]pub struct AutoImproveSettings {+ /// Background scheduler settings. This controls whether reviews are launched+ /// automatically; it does not control whether accepted proposals are applied.+ pub scheduler: AutoImproveSchedulerSettings,/// Require manual pending-writes approval. Defaults false so validated/// proposals are staged for audit and immediately approved through the/// normal wiki write path.@@ -391,9 +395,35 @@ pub struct AutoImproveSettings {pub pending_path: String,}+/// `[auto_improve.scheduler]` background learning loop settings.+#[derive(Debug, Clone, Serialize, Deserialize)]+#[serde(default)]+pub struct AutoImproveSchedulerSettings {+ /// Whether the server should periodically review newly-completed sessions.+ pub enabled: bool,+ /// Scheduler cadence. `0` disables the scheduler while keeping manual runs.+ pub interval_secs: u64,+ /// Maximum sessions reviewed per scheduler tick. `0` disables the scheduler.+ pub max_sessions_per_tick: usize,+ /// Minimum age after SessionEnd before a session becomes eligible.+ pub min_session_age_secs: u64,+}++impl Default for AutoImproveSchedulerSettings {+ fn default() -> Self {+ Self {+ enabled: true,+ interval_secs: 3_600,+ max_sessions_per_tick: 1,+ min_session_age_secs: 600,+ }+ }+}+impl Default for AutoImproveSettings {fn default() -> Self {Self {+ scheduler: AutoImproveSchedulerSettings::default(),require_approval: false,on_session_end: false,min_observations: ai_memory_consolidate::DEFAULT_AUTO_IMPROVE_MIN_OBSERVATIONS,@@ -791,6 +821,10 @@ mod tests {assert_eq!(cfg.maintenance.forget_sweep_interval_secs, 86_400);assert_eq!(cfg.maintenance.lint_interval_secs, 86_400);assert_eq!(cfg.maintenance.embedding_backfill_interval_secs, 0);+ assert!(cfg.auto_improve.scheduler.enabled);+ assert_eq!(cfg.auto_improve.scheduler.interval_secs, 3_600);+ assert_eq!(cfg.auto_improve.scheduler.max_sessions_per_tick, 1);+ assert_eq!(cfg.auto_improve.scheduler.min_session_age_secs, 600);assert!(!cfg.auto_improve.on_session_end);assert!(!cfg.auto_improve.require_approval);assert_eq!(cfg.auto_improve.min_observations, 8);@@ -849,6 +883,12 @@ mod tests {include_raw_fallback = trueproposal_actor = "review_bot"pending_path = "_pending/review-bot"++ [auto_improve.scheduler]+ enabled = true+ interval_secs = 1800+ max_sessions_per_tick = 4+ min_session_age_secs = 30"#,).unwrap();@@ -860,6 +900,10 @@ mod tests {assert_eq!(cfg.log_level, "debug");assert!(!cfg.maintenance.enabled);assert_eq!(cfg.maintenance.lint_interval_secs, 3600);+ assert!(cfg.auto_improve.scheduler.enabled);+ assert_eq!(cfg.auto_improve.scheduler.interval_secs, 1_800);+ assert_eq!(cfg.auto_improve.scheduler.max_sessions_per_tick, 4);+ assert_eq!(cfg.auto_improve.scheduler.min_session_age_secs, 30);assert!(cfg.auto_improve.on_session_end);assert!(cfg.auto_improve.require_approval);assert_eq!(cfg.auto_improve.min_observations, 3);diff --git a/crates/ai-memory-cli/templates/config.default.toml b/crates/ai-memory-cli/templates/config.default.tomlindex 6ec21e83..11fb6599 100644--- a/crates/ai-memory-cli/templates/config.default.toml+++ b/crates/ai-memory-cli/templates/config.default.toml@@ -77,10 +77,11 @@ allowlist = []# Auto-improvement reviewer.#-# Manual CLI/admin/MCP runs stage validated proposals in the pending-writes queue-# for audit, then approve them immediately by default through the normal wiki-# write path. Set `require_approval = true` to keep proposals pending until an-# admin runs `ai-memory pending-writes approve <id>`.+# The background scheduler reviews newly-completed sessions when an LLM provider+# is configured. Approval is a separate stage: by default proposals are staged+# for audit and immediately approved through the normal wiki write path. Set+# `require_approval = true` to keep scheduler and manual-run proposals pending+# until an admin runs `ai-memory pending-writes approve <id>`.## Older configs may still contain an `[auto_improve] mode = ...` line. That key# is ignored by current ai-memory and can be removed when convenient.@@ -94,3 +95,9 @@ max_proposals_per_run = 5include_raw_fallback = falseproposal_actor = "auto_improve"pending_path = "_pending/auto-improve"++[auto_improve.scheduler]+enabled = true+interval_secs = 3600+max_sessions_per_tick = 1+min_session_age_secs = 600diff --git a/crates/ai-memory-core/src/routing_snippet.rs b/crates/ai-memory-core/src/routing_snippet.rsindex 8238b51a..8dcfd652 100644--- a/crates/ai-memory-core/src/routing_snippet.rs+++ b/crates/ai-memory-core/src/routing_snippet.rs@@ -70,7 +70,7 @@ match the intent to the tool. They do not need to name the tool.| "save context for the next session" / wrapping up / ending this session | `memory_handoff_begin` (session-end only; do **not** use for status/briefing; single-use handoff; terse summary; put detail in `open_questions` + `next_steps` bullets; pass `workspace` + `project` together only for a named sibling workspace/project) || "discard that handoff" / "I created a handoff by mistake" | `memory_handoff_cancel` (requires exact `handoff_id` from `memory_handoff_begin`; marks it expired before the next session sees it) || "consolidate this session" / "compile what we learned" (also runs on PreCompact; at session end only if `AI_MEMORY_CONSOLIDATE_ON_SESSION_END` is set) | `memory_consolidate` |-| "what did we learn from this session?" / "what memory should we add?" / explicit wrap-up learning review | `memory_auto_improve` (reviews a completed session and applies validated wiki edits through the auto-improvement approval path; omit `session_id` for latest completed session) |+| "what did we learn from this session?" / "what memory should we add?" / explicit wrap-up learning review | `memory_auto_improve` (manual learning review for a completed session; omit `session_id` for latest completed session; the server also schedules background review for newly completed sessions when configured) || "remember this permanently" / "save a note" / "add an annotation" / durable project knowledge | `memory_write_page` (write a wiki page; do **not** use handoff for permanent notes; put the title as a `# H1` on the first line of `body` and omit the `title` arg — ai-memory derives it from the H1) || "read the page about X" / "show me the full content of Y" / "open the page on Z" | `memory_read_page` (full body; pass a query to search or `path` for a direct lookup; pass `workspace` + `project` together only for a named sibling workspace/project) || "delete the page X" / "remove that note" | `memory_delete_page` (by exact `path`; idempotent; pass `workspace` + `project` together only for a named sibling workspace/project) |@@ -124,11 +124,14 @@ query specific error/subsystem terms before designing a fix.### Learning Review-`memory_auto_improve` is a learning reviewer that applies validated wiki edits-through the auto-improvement approval path. Use it when the user asks what-durable lessons this session suggests, or at explicit wrap-up when reviewing-proposed memory would be useful. Admins can opt into manual review with-`[auto_improve] require_approval = true`, in which case proposals stay in+The server schedules background auto-improvement for newly completed sessions+when an LLM provider is configured. `memory_auto_improve` is the manual version:+use it when the user asks what durable lessons this session suggests, or at+explicit wrap-up when reviewing proposed memory would be useful. Scheduled and+manual runs apply or stage validated edits through the auto-improvement approval+path. Admins can turn off scheduling with `[auto_improve.scheduler] enabled =+false`, or opt into manual proposal approval with `[auto_improve]+require_approval = true`, in which case scheduled and manual proposals stay inpending-writes until approved.### When you write a project rule, write it herediff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rsindex da1930f1..6741c337 100644--- a/crates/ai-memory-mcp/src/admin.rs+++ b/crates/ai-memory-mcp/src/admin.rs@@ -4,7 +4,7 @@//! - `POST /admin/backup` — snapshot db + wiki into a gzip tarball (binary response).//! - `POST /admin/bootstrap` — ingest a pre-collected source bundle//! into seed wiki pages via the configured LLM provider.-//! - `POST /admin/auto-improve` — review one session and stage proposals.+//! - `POST /admin/auto-improve` — review one session and apply or stage proposals.//! - `POST /admin/curator` — dry-run or stage a rule-based curator report.//! - `GET /admin/status` — lifetime counts + server data-dir info.//! - `GET /admin/search?q=` — FTS5 hits against the wiki index.diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rsindex 55b37066..89722735 100644--- a/crates/ai-memory-mcp/src/server.rs+++ b/crates/ai-memory-mcp/src/server.rs@@ -92,11 +92,13 @@ the conversation calls for them:\n\observations into wiki pages. Also runs on PreCompact, and at \session end only when AI_MEMORY_CONSOLIDATE_ON_SESSION_END is set.\n\- `memory_auto_improve` — when the user asks what durable lessons \- should be proposed from a completed session, or at explicit wrap-up \- when learning review is useful. It reads the latest completed session \- by default and applies validated edits through the auto-improvement \- approval path. Admins can set `[auto_improve] require_approval = true` \- to leave proposals in pending-writes for manual review.\n\+should be proposed from a completed session, or at explicit wrap-up \+ when learning review is useful. It is the manual version of the server's \+ scheduled auto-improvement loop, reads the latest completed session by \+ default, and applies or stages validated edits through the auto-improvement \+ approval path. Admins can set `[auto_improve.scheduler] enabled = false` \+ to stop scheduling, or `[auto_improve] require_approval = true` to leave \+ scheduled and manual proposals in pending-writes for review.\n\- `memory_write_page` — when the user explicitly asks to remember, \save, or annotate durable project knowledge. This writes a wiki page; \do NOT use `memory_handoff_begin` for permanent annotations. \@@ -1163,7 +1165,7 @@ impl AiMemoryServer {/// Stage durable wiki edit proposals for a completed session.#[tool(- description = "Run auto-improvement for one completed session and apply validated wiki edit proposals through the auto-improvement approval path. Use when the user asks what durable lessons should be captured, what memory pages this session suggests, or at explicit wrap-up when a learning review is useful. Omit `session_id` to review the latest completed session in the current project. Admins can set `[auto_improve] require_approval = true` to leave proposals pending for manual review."+ description = "Run manual auto-improvement for one completed session and apply or stage validated wiki edit proposals through the auto-improvement approval path. Use when the user asks what durable lessons should be captured, what memory pages this session suggests, or at explicit wrap-up when a learning review is useful. Omit `session_id` to review the latest completed session in the current project. The server also schedules background review for newly completed sessions when an LLM provider is configured. Admins can set `[auto_improve.scheduler] enabled = false` to stop automatic review, or `[auto_improve] require_approval = true` to leave scheduled and manual proposals pending for review.")]async fn memory_auto_improve(&self,@@ -2418,7 +2420,8 @@ mod tests {let lower = prompt.to_ascii_lowercase();assert!(prompt.contains("memory_auto_improve"));assert!(- lower.contains("applies validated") || lower.contains("approval path"),+ lower.contains("applies validated")+ || (lower.contains("approval") && lower.contains("path")),"prompt must state auto-improve applies through the approval path");assert!(@@ -2437,7 +2440,7 @@ mod tests {.description.as_deref().expect("memory_auto_improve must carry a description");- assert!(desc.contains("apply validated"));+ assert!(desc.contains("apply or stage validated"));assert!(desc.contains("approval"));}diff --git a/crates/ai-memory-store/migrations/V22__auto_improve_scheduler.sql b/crates/ai-memory-store/migrations/V22__auto_improve_scheduler.sqlnew file mode 100644index 00000000..d05120c7--- /dev/null+++ b/crates/ai-memory-store/migrations/V22__auto_improve_scheduler.sql@@ -0,0 +1,54 @@+-- Background auto-improvement scheduler state and lookup indexes.++CREATE TABLE auto_improve_scheduler_state (+ workspace_id BLOB NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,+ project_id BLOB NOT NULL REFERENCES projects(id) ON DELETE CASCADE,+ watermark_ended_at INTEGER NOT NULL,+ initialized_at INTEGER NOT NULL,+ updated_at INTEGER NOT NULL,+ PRIMARY KEY (workspace_id, project_id)+);++CREATE TABLE auto_improve_scheduler_claims (+ workspace_id BLOB NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,+ project_id BLOB NOT NULL REFERENCES projects(id) ON DELETE CASCADE,+ session_id BLOB NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,+ claimed_at INTEGER NOT NULL,+ PRIMARY KEY (session_id)+);++CREATE INDEX idx_auto_improve_scheduler_claims_scope_session+ ON auto_improve_scheduler_claims(workspace_id, project_id, session_id);++CREATE INDEX idx_sessions_scope_ended+ ON sessions(workspace_id, project_id, ended_at ASC)+ WHERE ended_at IS NOT NULL;++CREATE INDEX idx_auto_improve_runs_scope_session+ ON auto_improve_runs(workspace_id, project_id, session_id)+ WHERE session_id IS NOT NULL;++CREATE TRIGGER auto_improve_scheduler_state_ws_proj_pairing_ai+BEFORE INSERT ON auto_improve_scheduler_state+FOR EACH ROW+WHEN NEW.workspace_id IS NOT (SELECT workspace_id FROM projects WHERE id = NEW.project_id)+BEGIN+ SELECT RAISE(ABORT, 'auto_improve_scheduler_state.workspace_id does not match the project''s workspace');+END;++CREATE TRIGGER auto_improve_scheduler_claims_ws_proj_pairing_ai+BEFORE INSERT ON auto_improve_scheduler_claims+FOR EACH ROW+WHEN NEW.workspace_id IS NOT (SELECT workspace_id FROM projects WHERE id = NEW.project_id)+BEGIN+ SELECT RAISE(ABORT, 'auto_improve_scheduler_claims.workspace_id does not match the project''s workspace');+END;++CREATE TRIGGER auto_improve_scheduler_claims_session_pairing_ai+BEFORE INSERT ON auto_improve_scheduler_claims+FOR EACH ROW+WHEN NEW.workspace_id IS NOT (SELECT workspace_id FROM sessions WHERE id = NEW.session_id)+ OR NEW.project_id IS NOT (SELECT project_id FROM sessions WHERE id = NEW.session_id)+BEGIN+ SELECT RAISE(ABORT, 'auto_improve_scheduler_claims scope does not match the session scope');+END;diff --git a/crates/ai-memory-store/src/auto_improve.rs b/crates/ai-memory-store/src/auto_improve.rsindex 1ec50f3b..f428fb68 100644--- a/crates/ai-memory-store/src/auto_improve.rs+++ b/crates/ai-memory-store/src/auto_improve.rs@@ -203,6 +203,83 @@ pub fn artifact_path_for(proposal_id: AutoImproveProposalId) -> String {format!("_pending/auto-improve/{proposal_id}.md")}+pub fn ensure_scheduler_state(+ conn: &mut Connection,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+) -> StoreResult<()> {+ let now = Timestamp::now().as_microsecond();+ let watermark_ended_at = conn.query_row(+ "SELECT COALESCE(MAX(ended_at), 0) FROM sessions \+ WHERE workspace_id = ?1 AND project_id = ?2 AND ended_at IS NOT NULL",+ params![workspace_id.as_bytes(), project_id.as_bytes()],+ |row| row.get::<_, i64>(0),+ )?;+ conn.execute(+ "INSERT INTO auto_improve_scheduler_state \+ (workspace_id, project_id, watermark_ended_at, initialized_at, updated_at) \+ VALUES (?1, ?2, ?3, ?4, ?4) \+ ON CONFLICT(workspace_id, project_id) DO NOTHING",+ params![+ workspace_id.as_bytes(),+ project_id.as_bytes(),+ watermark_ended_at,+ now,+ ],+ )?;+ Ok(())+}++pub fn claim_scheduler_session(+ conn: &mut Connection,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ session_id: SessionId,+ ended_at: i64,+) -> StoreResult<bool> {+ let now = Timestamp::now().as_microsecond();+ let tx = conn.transaction()?;+ let inserted = tx.execute(+ "INSERT OR IGNORE INTO auto_improve_scheduler_claims \+ (workspace_id, project_id, session_id, claimed_at) \+ SELECT ?1, ?2, ?3, ?4 \+ WHERE EXISTS ( \+ SELECT 1 FROM auto_improve_scheduler_state st \+ JOIN sessions s \+ ON s.workspace_id = st.workspace_id \+ AND s.project_id = st.project_id \+ WHERE st.workspace_id = ?1 \+ AND st.project_id = ?2 \+ AND s.id = ?3 \+ AND s.ended_at = ?5 \+ AND s.ended_at > st.watermark_ended_at \+ ) \+ AND NOT EXISTS ( \+ SELECT 1 FROM auto_improve_runs r \+ WHERE r.workspace_id = ?1 \+ AND r.project_id = ?2 \+ AND r.session_id = ?3 \+ )",+ params![+ workspace_id.as_bytes(),+ project_id.as_bytes(),+ session_id.as_bytes(),+ now,+ ended_at,+ ],+ )?;+ if inserted == 1 {+ tx.execute(+ "UPDATE auto_improve_scheduler_state \+ SET updated_at = ?3 \+ WHERE workspace_id = ?1 AND project_id = ?2",+ params![workspace_id.as_bytes(), project_id.as_bytes(), now],+ )?;+ }+ tx.commit()?;+ Ok(inserted == 1)+}+pub fn stage_run(conn: &mut Connection,input: &StageAutoImproveRun,diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rsindex bc2c688b..6f0b712c 100644--- a/crates/ai-memory-store/src/lib.rs+++ b/crates/ai-memory-store/src/lib.rs@@ -35,9 +35,9 @@ pub use decay::{DecayParams, retention_score};pub use error::{StoreError, StoreResult};pub use ops::{EmbeddingWrite, MoveSummary, PurgeSummary, ReorgSummary};pub use reader::{- ActivityWindow, BriefingPage, BriefingSnapshot, DecayCandidate, DerivedIndexStatus,- EmbeddingTripleCount, HealthDetail, HealthPage, ObservationHit, PageAuthor, PageHit,- PageHitWithMeta, PageLinks, PageMeta, PageSummary, ProjectSummary, ReaderPool,+ ActivityWindow, AutoImproveCandidateSession, BriefingPage, BriefingSnapshot, DecayCandidate,+ DerivedIndexStatus, EmbeddingTripleCount, HealthDetail, HealthPage, ObservationHit, PageAuthor,+ PageHit, PageHitWithMeta, PageLinks, PageMeta, PageSummary, ProjectSummary, ReaderPool,ReindexTargetStatus, RelatedPage, ScopeRow, StatusCounts, StoredEmbedding, StoredPageBody,WorkspaceScopeRow, WorkspaceSummary, f32_vec_to_bytes,};@@ -789,6 +789,48 @@ mod tests {.get_or_create_project(src_ws, "app", None).await.unwrap();+ store+ .writer+ .ensure_auto_improve_scheduler_state(src_ws, proj)+ .await+ .unwrap();+ tokio::time::sleep(std::time::Duration::from_millis(1)).await;+ let claimed_session = SessionId::new();+ store+ .writer+ .begin_session(NewSession {+ id: claimed_session,+ workspace_id: src_ws,+ project_id: proj,+ agent_kind: AgentKind::OpenCode,+ cwd: None,+ })+ .await+ .unwrap();+ store+ .writer+ .end_session(claimed_session, None)+ .await+ .unwrap();+ let candidate = store+ .reader+ .auto_improve_candidate_sessions(src_ws, proj, 0, 1)+ .await+ .unwrap()+ .pop()+ .unwrap();+ assert!(+ store+ .writer+ .claim_auto_improve_scheduler_session(+ src_ws,+ proj,+ candidate.session_id,+ candidate.ended_at,+ )+ .await+ .unwrap()+ );let proposal_id = store.writer.stage_auto_improve_run(stage_input(@@ -810,6 +852,8 @@ mod tests {.unwrap();assert_eq!(summary.auto_improve_runs_moved, 1);assert_eq!(summary.auto_improve_proposals_moved, 1);+ assert_eq!(summary.auto_improve_scheduler_state_moved, 1);+ assert_eq!(summary.auto_improve_scheduler_claims_moved, 1);assert!(store.reader@@ -826,6 +870,15 @@ mod tests {.unwrap().is_some());+ assert!(+ store+ .reader+ .auto_improve_candidate_sessions(dst_ws, proj, 0, 10)+ .await+ .unwrap()+ .is_empty(),+ "moved scheduler claims should keep claimed sessions suppressed"+ );}#[tokio::test]@@ -1470,6 +1523,446 @@ mod tests {);}+ #[tokio::test]+ async fn auto_improve_scheduler_candidates_respect_watermark_age_and_runs() {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let ws = store+ .writer+ .get_or_create_workspace("default")+ .await+ .unwrap();+ let proj = store+ .writer+ .get_or_create_project(ws, "ai-memory", None)+ .await+ .unwrap();++ let historical = SessionId::new();+ store+ .writer+ .begin_session(NewSession {+ id: historical,+ workspace_id: ws,+ project_id: proj,+ agent_kind: AgentKind::OpenCode,+ cwd: None,+ })+ .await+ .unwrap();+ store.writer.end_session(historical, None).await.unwrap();++ store+ .writer+ .ensure_auto_improve_scheduler_state(ws, proj)+ .await+ .unwrap();+ // Restart/idempotency: the second call must not reset the watermark.+ store+ .writer+ .ensure_auto_improve_scheduler_state(ws, proj)+ .await+ .unwrap();++ tokio::time::sleep(std::time::Duration::from_millis(1)).await;++ let fresh_after_watermark = SessionId::new();+ let open_after_watermark = SessionId::new();+ for id in [fresh_after_watermark, open_after_watermark] {+ store+ .writer+ .begin_session(NewSession {+ id,+ workspace_id: ws,+ project_id: proj,+ agent_kind: AgentKind::OpenCode,+ cwd: None,+ })+ .await+ .unwrap();+ }+ store+ .writer+ .end_session(fresh_after_watermark, None)+ .await+ .unwrap();++ assert!(+ store+ .reader+ .auto_improve_candidate_sessions(ws, proj, 86_400, 10)+ .await+ .unwrap()+ .is_empty(),+ "too-fresh completed sessions must not be candidates"+ );++ let candidates = store+ .reader+ .auto_improve_candidate_sessions(ws, proj, 0, 10)+ .await+ .unwrap();+ assert_eq!(candidates.len(), 1);+ assert_eq!(candidates[0].session_id, fresh_after_watermark);++ assert!(+ store+ .writer+ .claim_auto_improve_scheduler_session(+ ws,+ proj,+ candidates[0].session_id,+ candidates[0].ended_at,+ )+ .await+ .unwrap(),+ "first scheduler claim should be recorded"+ );+ assert!(+ !store+ .writer+ .claim_auto_improve_scheduler_session(+ ws,+ proj,+ candidates[0].session_id,+ candidates[0].ended_at,+ )+ .await+ .unwrap(),+ "duplicate scheduler claims should be rejected"+ );+ assert!(+ store+ .reader+ .auto_improve_candidate_sessions(ws, proj, 0, 10)+ .await+ .unwrap()+ .is_empty(),+ "claimed sessions must not be retried if review fails before staging"+ );++ tokio::time::sleep(std::time::Duration::from_millis(1)).await;+ let reviewed_after_watermark = SessionId::new();+ store+ .writer+ .begin_session(NewSession {+ id: reviewed_after_watermark,+ workspace_id: ws,+ project_id: proj,+ agent_kind: AgentKind::OpenCode,+ cwd: None,+ })+ .await+ .unwrap();+ store+ .writer+ .end_session(reviewed_after_watermark, None)+ .await+ .unwrap();++ store+ .writer+ .stage_auto_improve_run(StageAutoImproveRun {+ workspace_id: ws,+ project_id: proj,+ session_id: Some(reviewed_after_watermark),+ provider: Some("none".into()),+ model: Some("none".into()),+ summary: Some("reviewed".into()),+ warnings_json: serde_json::json!([]),+ rejected_candidates_json: serde_json::json!([]),+ config_json: serde_json::json!({ "trigger": "scheduler" }),+ proposal_actor: ActorContext {+ agent: Some("auto_improve".into()),+ ..ActorContext::default()+ },+ proposals: Vec::new(),+ })+ .await+ .unwrap();++ assert!(+ store+ .reader+ .auto_improve_candidate_sessions(ws, proj, 0, 10)+ .await+ .unwrap()+ .is_empty(),+ "any recorded run row suppresses scheduler retry for v1"+ );+ }++ #[tokio::test]+ async fn auto_improve_scheduler_claims_do_not_skip_same_ended_at_sessions() {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let ws = store+ .writer+ .get_or_create_workspace("default")+ .await+ .unwrap();+ let proj = store+ .writer+ .get_or_create_project(ws, "ai-memory", None)+ .await+ .unwrap();+ store+ .writer+ .ensure_auto_improve_scheduler_state(ws, proj)+ .await+ .unwrap();++ tokio::time::sleep(std::time::Duration::from_millis(1)).await;+ let first = SessionId::new();+ let second = SessionId::new();+ for id in [first, second] {+ store+ .writer+ .begin_session(NewSession {+ id,+ workspace_id: ws,+ project_id: proj,+ agent_kind: AgentKind::OpenCode,+ cwd: None,+ })+ .await+ .unwrap();+ store.writer.end_session(id, None).await.unwrap();+ }++ let same_ended_at = jiff::Timestamp::now().as_microsecond();+ let conn = Connection::open(store.db_path()).unwrap();+ conn.execute(+ "UPDATE sessions SET ended_at = ?1 WHERE id IN (?2, ?3)",+ params![same_ended_at, first.as_bytes(), second.as_bytes()],+ )+ .unwrap();++ let candidates = store+ .reader+ .auto_improve_candidate_sessions(ws, proj, 0, 10)+ .await+ .unwrap();+ assert_eq!(candidates.len(), 2);+ assert!(+ store+ .writer+ .claim_auto_improve_scheduler_session(+ ws,+ proj,+ candidates[0].session_id,+ candidates[0].ended_at,+ )+ .await+ .unwrap()+ );++ let remaining = store+ .reader+ .auto_improve_candidate_sessions(ws, proj, 0, 10)+ .await+ .unwrap();+ assert_eq!(remaining.len(), 1);+ assert_ne!(remaining[0].session_id, candidates[0].session_id);+ assert_eq!(remaining[0].ended_at, same_ended_at);+ }++ #[tokio::test]+ async fn auto_improve_scheduler_claim_is_unique_across_store_instances() {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let ws = store+ .writer+ .get_or_create_workspace("default")+ .await+ .unwrap();+ let proj = store+ .writer+ .get_or_create_project(ws, "ai-memory", None)+ .await+ .unwrap();+ store+ .writer+ .ensure_auto_improve_scheduler_state(ws, proj)+ .await+ .unwrap();+ tokio::time::sleep(std::time::Duration::from_millis(1)).await;++ let session_id = SessionId::new();+ store+ .writer+ .begin_session(NewSession {+ id: session_id,+ workspace_id: ws,+ project_id: proj,+ agent_kind: AgentKind::OpenCode,+ cwd: None,+ })+ .await+ .unwrap();+ store.writer.end_session(session_id, None).await.unwrap();+ let ended_at = store+ .reader+ .auto_improve_candidate_sessions(ws, proj, 0, 1)+ .await+ .unwrap()[0]+ .ended_at;++ let second_store = Store::open(tmp.path()).unwrap();+ let (first, second) = tokio::join!(+ store+ .writer+ .claim_auto_improve_scheduler_session(ws, proj, session_id, ended_at),+ second_store+ .writer+ .claim_auto_improve_scheduler_session(ws, proj, session_id, ended_at),+ );+ let claimed = [first.unwrap(), second.unwrap()];+ assert_eq!(claimed.into_iter().filter(|claimed| *claimed).count(), 1);++ let conn = Connection::open(store.db_path()).unwrap();+ let claim_rows: i64 = conn+ .query_row(+ "SELECT COUNT(*) FROM auto_improve_scheduler_claims WHERE session_id = ?1",+ params![session_id.as_bytes()],+ |row| row.get(0),+ )+ .unwrap();+ assert_eq!(claim_rows, 1);+ }++ #[tokio::test]+ async fn v103_schema_upgrades_to_current_without_backlog_or_integrity_breaks() {+ let tmp = TempDir::new().unwrap();+ let db_dir = tmp.path().join("db");+ std::fs::create_dir_all(&db_dir).unwrap();+ let db_path = db_dir.join(DB_FILENAME);++ let session_id = SessionId::new();+ {+ let mut conn = Connection::open(&db_path).unwrap();+ conn.pragma_update(None, "foreign_keys", "OFF").unwrap();+ super::migrations::run_to(&mut conn, 19).unwrap();+ conn.pragma_update(None, "foreign_keys", "ON").unwrap();++ let ws = super::ops::get_or_create_workspace(&mut conn, "default").unwrap();+ let proj =+ super::ops::get_or_create_project(&mut conn, &ws, "ai-memory", None).unwrap();+ let page_id = super::ops::upsert_page(+ &mut conn,+ &sample_page(ws, proj, "notes/v103.md", "v1.0.3 upgrade fixture"),+ )+ .unwrap();+ super::ops::begin_session(+ &mut conn,+ &NewSession {+ id: session_id,+ workspace_id: ws,+ project_id: proj,+ agent_kind: AgentKind::OpenCode,+ cwd: None,+ },+ )+ .unwrap();+ super::ops::insert_observation(+ &mut conn,+ &NewObservation {+ session_id,+ workspace_id: ws,+ project_id: proj,+ kind: ObservationKind::UserPrompt,+ extension: None,+ source_event: None,+ title: "prompt".into(),+ body: "upgrade observation survives".into(),+ importance: 5,+ },+ )+ .unwrap();+ super::ops::end_session(&mut conn, &session_id, Some(&page_id)).unwrap();+ }++ let store = Store::open(tmp.path()).unwrap();+ let ws = store+ .writer+ .get_or_create_workspace("default")+ .await+ .unwrap();+ let proj = store+ .writer+ .get_or_create_project(ws, "ai-memory", None)+ .await+ .unwrap();++ assert_eq!(+ store+ .reader+ .latest_completed_session_for_project(ws, proj)+ .await+ .unwrap(),+ Some(session_id)+ );+ assert_eq!(+ store+ .reader+ .search_observations_for_project(ws, proj, "upgrade".into(), 10)+ .await+ .unwrap()+ .len(),+ 1+ );+ let page = store+ .reader+ .page_body_by_ids(ws, proj, "notes/v103.md")+ .await+ .unwrap()+ .unwrap();+ assert_eq!(page.body, "v1.0.3 upgrade fixture");++ store+ .writer+ .ensure_auto_improve_scheduler_state(ws, proj)+ .await+ .unwrap();+ assert!(+ store+ .reader+ .auto_improve_candidate_sessions(ws, proj, 0, 10)+ .await+ .unwrap()+ .is_empty(),+ "v1.0.3-era completed sessions must become the first-run watermark, not backlog"+ );++ let conn = Connection::open(store.db_path()).unwrap();+ let integrity: String = conn+ .query_row("PRAGMA integrity_check", [], |row| row.get(0))+ .unwrap();+ assert_eq!(integrity, "ok");+ let fk_violations: i64 = conn+ .query_row("SELECT COUNT(*) FROM pragma_foreign_key_check", [], |row| {+ row.get(0)+ })+ .unwrap();+ assert_eq!(fk_violations, 0);+ for table in [+ "auto_improve_runs",+ "auto_improve_proposals",+ "auto_improve_proposal_events",+ "auto_improve_scheduler_state",+ "auto_improve_scheduler_claims",+ ] {+ let exists: i64 = conn+ .query_row(+ "SELECT COUNT(*) FROM sqlite_master WHERE type = 'table' AND name = ?1",+ params![table],+ |row| row.get(0),+ )+ .unwrap();+ assert_eq!(exists, 1, "{table} should exist after v1.0.3 upgrade");+ }+ }+#[tokio::test]async fn list_projects_with_stats_returns_aggregates() {let tmp = TempDir::new().unwrap();diff --git a/crates/ai-memory-store/src/ops.rs b/crates/ai-memory-store/src/ops.rsindex 7f5e53a1..e5d10999 100644--- a/crates/ai-memory-store/src/ops.rs+++ b/crates/ai-memory-store/src/ops.rs@@ -1157,6 +1157,10 @@ pub struct MoveSummary {pub auto_improve_runs_moved: u64,/// `auto_improve_proposals` rows re-stamped.pub auto_improve_proposals_moved: u64,+ /// `auto_improve_scheduler_state` rows re-stamped.+ pub auto_improve_scheduler_state_moved: u64,+ /// `auto_improve_scheduler_claims` rows re-stamped.+ pub auto_improve_scheduler_claims_moved: u64,}/// Re-stamp a project's `workspace_id` across every domain table in ONE@@ -1218,6 +1222,14 @@ pub fn move_project_workspace("UPDATE auto_improve_proposals SET workspace_id = ?1 WHERE project_id = ?2 AND workspace_id = ?3",params![&to[..], &pid[..], &from[..]],)? as u64;+ let auto_improve_scheduler_state_moved = tx.execute(+ "UPDATE auto_improve_scheduler_state SET workspace_id = ?1 WHERE project_id = ?2 AND workspace_id = ?3",+ params![&to[..], &pid[..], &from[..]],+ )? as u64;+ let auto_improve_scheduler_claims_moved = tx.execute(+ "UPDATE auto_improve_scheduler_claims SET workspace_id = ?1 WHERE project_id = ?2 AND workspace_id = ?3",+ params![&to[..], &pid[..], &from[..]],+ )? as u64;let projects_updated = tx.execute("UPDATE projects SET workspace_id = ?1 WHERE id = ?2 AND workspace_id = ?3",@@ -1238,6 +1250,8 @@ pub fn move_project_workspace(audit_log_moved,auto_improve_runs_moved,auto_improve_proposals_moved,+ auto_improve_scheduler_state_moved,+ auto_improve_scheduler_claims_moved,})}diff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rsindex eb694d06..c2d247f7 100644--- a/crates/ai-memory-store/src/reader.rs+++ b/crates/ai-memory-store/src/reader.rs@@ -14,6 +14,7 @@ use ai_memory_core::{AgentKind, AutoImproveProposalId, Handoff, HandoffId, HandoffState, Observation, ObservationId,ObservationKind, PageId, PagePath, ProjectId, SessionId, User, UserId, WorkspaceId,};+use jiff::Timestamp;use parking_lot::Mutex;use rusqlite::types::Value;use rusqlite::{Connection, OpenFlags, OptionalExtension, params, params_from_iter};@@ -45,6 +46,15 @@ pub struct PageHit {pub rank: f64,}+/// Completed session selected for scheduled auto-improvement.+#[derive(Debug, Clone, Copy, PartialEq, Eq)]+pub struct AutoImproveCandidateSession {+ /// Session id.+ pub session_id: SessionId,+ /// Session `ended_at` timestamp in Unix microseconds.+ pub ended_at: i64,+}+/// The latest version of a page's stored content, used as a DB-backed/// fallback when the on-disk markdown read fails (index/disk skew). The/// markdown file is the source of truth, but the store keeps a faithful copy@@ -951,6 +961,89 @@ impl ReaderPool {.await}+ /// Return completed sessions eligible for scheduled auto-improvement.+ ///+ /// The scheduler uses a persisted first-run watermark so an upgrade with an+ /// LLM provider configured does not chew through historical backlog by+ /// default. The scheduler inserts a per-session claim before the LLM call,+ /// so failed scheduled reviews do not retry forever or starve newer+ /// sessions. Any existing auto-improvement run row for a session also counts+ /// as a scheduler review for candidate selection; manual reruns remain+ /// available through CLI/admin/MCP.+ ///+ /// # Errors+ /// Propagates any SQL or pool error.+ pub async fn auto_improve_candidate_sessions(+ &self,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ min_session_age_secs: u64,+ limit: usize,+ ) -> StoreResult<Vec<AutoImproveCandidateSession>> {+ let cutoff = Timestamp::now().as_microsecond().saturating_sub(+ (min_session_age_secs.min(i64::MAX as u64 / 1_000_000) as i64) * 1_000_000,+ );+ self.with_conn(move |conn| {+ let watermark: Option<i64> = conn+ .query_row(+ "SELECT watermark_ended_at FROM auto_improve_scheduler_state \+ WHERE workspace_id = ?1 AND project_id = ?2",+ params![workspace_id.as_bytes(), project_id.as_bytes()],+ |row| row.get(0),+ )+ .optional()?;+ let Some(watermark) = watermark else {+ return Ok(Vec::new());+ };++ let mut stmt = conn.prepare_cached(+ "SELECT s.id, s.ended_at FROM sessions s \+ WHERE s.workspace_id = ?1 \+ AND s.project_id = ?2 \+ AND s.ended_at IS NOT NULL \+ AND s.ended_at > ?3 \+ AND s.ended_at <= ?4 \+ AND NOT EXISTS ( \+ SELECT 1 FROM auto_improve_scheduler_claims c \+ WHERE c.workspace_id = s.workspace_id \+ AND c.project_id = s.project_id \+ AND c.session_id = s.id \+ ) \+ AND NOT EXISTS ( \+ SELECT 1 FROM auto_improve_runs r \+ WHERE r.workspace_id = s.workspace_id \+ AND r.project_id = s.project_id \+ AND r.session_id = s.id \+ ) \+ ORDER BY s.ended_at ASC, s.started_at ASC \+ LIMIT ?5",+ )?;+ let rows = stmt.query_map(+ params![+ workspace_id.as_bytes(),+ project_id.as_bytes(),+ watermark,+ cutoff,+ limit.min(i64::MAX as usize) as i64,+ ],+ |row| {+ let id_bytes: Vec<u8> = row.get(0)?;+ Ok((id_bytes, row.get::<_, i64>(1)?))+ },+ )?;+ let mut out = Vec::new();+ for row in rows {+ let (id_bytes, ended_at) = row?;+ out.push(AutoImproveCandidateSession {+ session_id: SessionId::from_slice(&id_bytes)?,+ ended_at,+ });+ }+ Ok(out)+ })+ .await+ }+/// Look up the `(workspace_id, project_id)` a session belongs to./// Returns `None` when no such session row exists.///diff --git a/crates/ai-memory-store/src/writer.rs b/crates/ai-memory-store/src/writer.rsindex 7f8b23c3..90c988d7 100644--- a/crates/ai-memory-store/src/writer.rs+++ b/crates/ai-memory-store/src/writer.rs@@ -210,6 +210,18 @@ pub(crate) enum WriteCmd {input: ApproveAutoImproveProposal,reply: oneshot::Sender<StoreResult<ApproveAutoImproveProposalResult>>,},+ EnsureAutoImproveSchedulerState {+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ reply: oneshot::Sender<StoreResult<()>>,+ },+ ClaimAutoImproveSchedulerSession {+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ session_id: SessionId,+ ended_at: i64,+ reply: oneshot::Sender<StoreResult<bool>>,+ },Shutdown,}@@ -852,6 +864,45 @@ impl WriterHandle {rx.await.map_err(|_| StoreError::WriterClosed)?}+ /// Initialise background auto-improvement scheduler state without resetting+ /// an existing watermark.+ pub async fn ensure_auto_improve_scheduler_state(+ &self,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ ) -> StoreResult<()> {+ let (tx, rx) = oneshot::channel();+ self.send(WriteCmd::EnsureAutoImproveSchedulerState {+ workspace_id,+ project_id,+ reply: tx,+ })+ .await?;+ rx.await.map_err(|_| StoreError::WriterClosed)?+ }++ /// Atomically claim a completed session for scheduled auto-improvement+ /// before any LLM work runs. Returns `false` if another scheduler/manual run+ /// already claimed or reviewed the session.+ pub async fn claim_auto_improve_scheduler_session(+ &self,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ session_id: SessionId,+ ended_at: i64,+ ) -> StoreResult<bool> {+ let (tx, rx) = oneshot::channel();+ self.send(WriteCmd::ClaimAutoImproveSchedulerSession {+ workspace_id,+ project_id,+ session_id,+ ended_at,+ reply: tx,+ })+ .await?;+ rx.await.map_err(|_| StoreError::WriterClosed)?+ }+async fn send(&self, cmd: WriteCmd) -> StoreResult<()> {self.inner.tx@@ -1137,6 +1188,34 @@ fn worker_loop(mut conn: Connection, mut rx: mpsc::Receiver<WriteCmd>) {let result = crate::auto_improve::approve_proposal(&mut conn, &input);send_or_warn(reply, result, "approve_auto_improve_proposal");}+ WriteCmd::EnsureAutoImproveSchedulerState {+ workspace_id,+ project_id,+ reply,+ } => {+ let result = crate::auto_improve::ensure_scheduler_state(+ &mut conn,+ workspace_id,+ project_id,+ );+ send_or_warn(reply, result, "ensure_auto_improve_scheduler_state");+ }+ WriteCmd::ClaimAutoImproveSchedulerSession {+ workspace_id,+ project_id,+ session_id,+ ended_at,+ reply,+ } => {+ let result = crate::auto_improve::claim_scheduler_session(+ &mut conn,+ workspace_id,+ project_id,+ session_id,+ ended_at,+ );+ send_or_warn(reply, result, "claim_auto_improve_scheduler_session");+ }}}tracing::debug!("writer thread exiting cleanly");diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex c2419d17..14e47152 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -28,11 +28,13 @@ Solid arrows are request, read, and write paths. Dashed arrows arebackground reconciliation or provider-backed maintenance. The core invariant isunchanged: the markdown wiki is the source of truth, and SQLite is the derivedindex for search, sessions, observations, handoffs, audit, and embeddings.-Auto-improvement sits on the provider-backed maintenance side: it reviews a-completed session, records validated proposals in the pending-writes audit trail,-and auto-approves them through the normal wiki write path by default. Admins can-set `[auto_improve] require_approval = true` to leave proposals pending for-manual review.+Auto-improvement sits on the provider-backed maintenance side: the server+schedules reviews for newly completed sessions, records validated proposals in+the pending-writes audit trail, and auto-approves them through the normal wiki+write path by default. Scheduling and approval are separate. Admins can set+`[auto_improve.scheduler] enabled = false` to stop background review, or+`[auto_improve] require_approval = true` to leave scheduled and manual proposals+pending for review.**Steady-state loop:**@@ -56,12 +58,16 @@ manual review.4. When `AI_MEMORY_LLM_PROVIDER` is set, `memory_consolidate` rewritesthat summary into a richer durable page or fans out into amulti-page batch under `concepts/`, `decisions/`, `gotchas/`.-5. On explicit CLI/admin/MCP request, auto-improvement reviews one completed- session with the configured LLM, records validated `concepts/`, `decisions/`,- `gotchas/`, `procedures/`, and `_rules/` proposals in the pending-writes- audit trail, then approves them through the wiki mutation path by default.- Auto-improvement does not run on SessionEnd by default. With- `[auto_improve] require_approval = true`, proposals remain pending until an+5. When an LLM provider is configured, the auto-improvement scheduler reviews+ newly completed sessions outside hook latency. It records validated+ `concepts/`, `decisions/`, `gotchas/`, `procedures/`, and `_rules/` proposals+ in the pending-writes audit trail, then approves them through the wiki+ mutation path by default. The scheduler initializes a per-project first-run+ watermark so historical sessions are not processed automatically on upgrade,+ then records per-session claims before LLM work so failed scheduled reviews do+ not retry forever. Explicit CLI/admin/MCP auto-improve calls use the same+ pipeline for targeted reruns or catch-up. With `[auto_improve]+ require_approval = true`, scheduled and manual proposals remain pending untilexplicit pending-writes approval.6. `memory_query` answers via FTS5 + link-neighbour RRF; when anembedder is configured, vector cosine over `page_embeddings` joins@@ -214,7 +220,7 @@ invariants below.| `memory_handoff_accept` | destructive | Fetch + ack the latest open handoff (auto-cwd-matched by default). Optional `workspace` + `project` targets a named sibling workspace/project. || `memory_handoff_cancel` | destructive | Mark an exact open handoff id expired when it was created by mistake. || `memory_consolidate` | destructive | LLM-driven page rewrite. `multi_page=true` for atomic fan-out. |-| `memory_auto_improve` | write | Review a completed session and apply validated wiki edits through the auto-improvement approval path. Defaults to the latest completed session in the resolved current project; `[auto_improve] require_approval = true` leaves proposals pending for manual review. |+| `memory_auto_improve` | write | Manually review a completed session and apply or stage validated wiki edits through the auto-improvement approval path. Defaults to the latest completed session in the resolved current project; the server also schedules review for new sessions; `[auto_improve] require_approval = true` leaves proposals pending for manual review. || `memory_write_page` | destructive | Write durable wiki knowledge when the user explicitly asks to remember/annotate something permanent. || `memory_delete_page` | destructive | Delete a single page by exact `path`. Fires the admission chain (op=delete); idempotent. || `memory_forget_sweep` | destructive | M8 retention pass. `dry_run=true` for preview. |@@ -330,6 +336,12 @@ max_proposals_per_run = 5include_raw_fallback = falseproposal_actor = "auto_improve"pending_path = "_pending/auto-improve"++[auto_improve.scheduler] # background review; separate from approval+enabled = true+interval_secs = 3600+max_sessions_per_tick = 1+min_session_age_secs = 600```**LLM provider env** (opt-in):@@ -371,9 +383,9 @@ LLM_API_KEY accepted for openai embeddings only with a customthousand pages; past that, the `sqlite-vec` extension is the nextstep. See [`docs/vector-backend-policy.md`](vector-backend-policy.md)for the criteria that should justify adding it.-* **Scheduled consolidation queue.** Forget sweep and lint already run- on the server's maintenance schedule; a future queue can compile- session summaries outside hook latency.+* **Scheduled consolidation queue.** Forget sweep, lint, and auto-improvement+ already run on server-side schedules; a future queue can compile session+ summaries outside hook latency.* **Richer curator actions.** The shipped curator stages only one report page;future work can add individual merge/supersession/link-fix proposals whilekeeping deletes and semantic rewrites review-gated.diff --git a/docs/architecture-overview.svg b/docs/architecture-overview.svgindex 39b6031d..aaabb5c5 100644--- a/docs/architecture-overview.svg+++ b/docs/architecture-overview.svg@@ -1,6 +1,6 @@<svg xmlns="http://www.w3.org/2000/svg" width="1400" height="920" viewBox="0 0 1400 920" role="img" aria-labelledby="title desc"><title id="title">ai-memory architecture overview</title>- <desc id="desc">A diagram showing agent clients sending lifecycle hooks and MCP calls into ai-memory serve, which routes through hook, MCP, web, admin, scope, auth, writer, read pool, markdown wiki, SQLite index, maintenance jobs, and optional LLM and embedding providers.</desc>+ <desc id="desc">A diagram showing agent clients sending lifecycle hooks and MCP calls into ai-memory serve, which routes through hook, MCP, web, admin, scope, auth, writer, read pool, markdown wiki, SQLite index, scheduled auto-improvement and maintenance jobs, and optional LLM and embedding providers.</desc><defs><marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="#334155" />@@ -61,7 +61,7 @@<rect class="external" x="1050" y="130" width="290" height="118" /><text class="box-title" x="1075" y="164">Optional providers</text><text class="box-text" x="1075" y="190">LLM consolidation and lint</text>- <text class="box-text" x="1075" y="211">auto-improvement review/approval</text>+ <text class="box-text" x="1075" y="211">scheduled review + approval</text><text class="box-text" x="1075" y="232">embedding vector backfill</text><rect class="server" x="60" y="300" width="1280" height="390" />@@ -98,10 +98,10 @@<text class="box-text" x="580" y="615">optional vector RRF + raw fallback</text><rect class="job" x="960" y="535" width="300" height="110" />- <text class="box-title" x="985" y="568">Lifecycle and maintenance jobs</text>+ <text class="box-title" x="985" y="568">Lifecycle and scheduled jobs</text><text class="box-text" x="985" y="594">session summary + handoff</text>- <text class="box-text" x="985" y="615">consolidate, auto-improve</text>- <text class="box-text" x="985" y="636">lint, embed, sweep</text>+ <text class="box-text" x="985" y="615">auto-improve scheduler</text>+ <text class="box-text" x="985" y="636">consolidate, lint, embed, sweep</text><text class="group-label" x="70" y="735">DURABLE STATE</text><rect class="store" x="105" y="755" width="350" height="120" />diff --git a/docs/auto-improvement-loop.md b/docs/auto-improvement-loop.mdindex 506c2371..f4f39d24 100644--- a/docs/auto-improvement-loop.md+++ b/docs/auto-improvement-loop.md@@ -1,10 +1,12 @@# Optional Auto-Improvement Loop Research-> Status: research plus implemented production notes. CLI/admin/MCP-> auto-improvement records validated proposals in the pending-writes audit trail-> and auto-approves them through the normal wiki write path by default. Admins-> can set `[auto_improve] require_approval = true` for manual review.-> Session-end triggers remain future work.+> Status: research plus implemented production notes. The server schedules+> auto-improvement for newly completed sessions when an LLM provider is+> configured. Manual CLI/admin/MCP auto-improvement remains available for+> targeted runs and catch-up. Both paths record validated proposals in the+> pending-writes audit trail and auto-approve them through the normal wiki write+> path by default. Admins can set `[auto_improve] require_approval = true` for+> manual review.## Executive Summary@@ -19,7 +21,8 @@ or silently promoting weak session residue into rules.The safe product shape is:1. Keep automatic observation capture and session consolidation as they are.-2. Add an optional background review pass that creates pending wiki edits.+2. Add a background review pass that creates pending wiki edits for newly+ completed sessions when an LLM provider is configured.3. Record proposals and apply them through the approval/audit path by default,with manual approval available as an admin opt-in.4. Keep a separate slow maintenance pass for deduplication, stale-page review,@@ -156,24 +159,28 @@ new memory substrate.## Recommendation-Build auto-improvement as a default-available review path that records proposal-provenance before writing target wiki pages. Manual CLI/admin/MCP runs apply-validated proposals through the same approval path used by pending-writes;-manual approval remains an admin opt-in.+Build auto-improvement as a default-available scheduled review path that records+proposal provenance before writing target wiki pages. Manual CLI/admin/MCP runs+use the same pipeline for targeted review or historical catch-up. Scheduling and+approval are separate: the scheduler decides when to review newly completed+sessions, and the approval policy decides whether validated proposals are applied+immediately or left pending for humans.The shipped feature is an audit-first learning reviewer:-1. CLI/admin/MCP auto-improvement is enabled when an LLM provider is configured.- Manual runs do not enable any session-end trigger.+1. Scheduled auto-improvement is enabled when an LLM provider is configured and+ `[auto_improve.scheduler] enabled = true`. Manual runs do not affect the+ scheduler.2. Reads a completed session, recent pages, and relevant existing wiki pages.3. Produces a structured proposal containing small page creates or updates.4. Stores the proposal in a pending-review queue with evidence and diffs.5. Applies approved proposals through `Wiki::apply_batch`, admission webhooks,auth capabilities, audit logging, and the single writer actor.-Auto-apply can be considered later for narrow, high-confidence updates, but the-current version earns trust by recording staged proposals and applying them-through the same approval path, while allowing admins to require manual review.+Auto-approval is the default, but it still records staged proposals and applies+them through the same approval path. Admins who want a human queue set+`[auto_improve] require_approval = true`; admins who want no automatic review set+`[auto_improve.scheduler] enabled = false`.## Proposed Page Targets@@ -210,27 +217,31 @@ The review prompt should explicitly reject these as durable learning:Any implementation should preserve these invariants:-1. Manual CLI/admin/MCP runs record proposals and auto-approve by default.-2. Automatic SessionEnd triggering is off by default.-3. Never mutate the active session prompt or already-prepended handoff context.-4. Never run inside hook latency. Hooks remain fire-and-forget and bounded.-5. Never bypass workspace/project isolation. Use `ScopeResolver` or its explicit+1. Scheduled and manual CLI/admin/MCP runs record proposals and auto-approve by+ default.+2. Scheduling and approval remain separate: disabling the scheduler does not+ require manual approvals, and requiring approvals does not stop scheduling.+3. Automatic SessionEnd triggering is off by default.+4. Never mutate the active session prompt or already-prepended handoff context.+5. Never run inside hook latency. Hooks remain fire-and-forget and bounded.+6. Never bypass workspace/project isolation. Use `ScopeResolver` or its explicithelpers for every read and write path.-6. Never bypass auth. Use `AuthLevel::authorize(Capability::...)` for all admin+7. Never bypass auth. Use `AuthLevel::authorize(Capability::...)` for all adminand write surfaces.-7. Never write wiki files directly from a handler or background worker. Use+8. Never write wiki files directly from a handler or background worker. Use`Wiki::write_page`, `Wiki::apply_batch`, or existing destructive helpers.-8. Never auto-delete semantic pages. Use supersession, pending proposals, or the+9. Never auto-delete semantic pages. Use supersession, pending proposals, or theexisting retention sweep for episodic pages.-9. Never rewrite pinned pages or invariant slots unless the proposal cites a+10. Never rewrite pinned pages or invariant slots unless the proposal cites adirect contradiction and is explicitly approved.-10. Include source evidence for every proposed edit.-11. Attribute autonomous proposals to a distinct `auto_improve` actor so audit+11. Include source evidence for every proposed edit.+12. Attribute autonomous proposals to a distinct `auto_improve` actor so auditlogs, admission webhooks, and review screens can distinguish machine-suggestedchanges from user/root writes.-12. Bound model cost, input size, output size, and number of proposed page+13. Bound model cost, input size, output size, and number of proposed pagemutations per run.-13. Write a human-readable and machine-readable report for each run.+14. Write a machine-readable audit row for every run and human-readable proposal+ sidecars whenever proposals exist.## Existing User Upgrade Contract@@ -239,15 +250,20 @@ Default-available auto-improvement must not surprise existing installs:1. Existing project wiki folders need no migration. Older configs may stillcontain an `[auto_improve] mode = ...` key; current ai-memory ignores thatlegacy key. Operators can remove the line when convenient.-2. Session-end triggering stays off until a bounded background scheduler exists;- hooks must not gain LLM latency as a side effect of upgrade.-3. Pending proposal storage must use additive, idempotent migrations that- preserve all existing wiki files and session/observation rows.-4. Existing installed `CLAUDE.md`/`AGENTS.md` blocks remain valid. Operators pick+2. Session-end triggering stays off; the bounded background scheduler runs+ outside hook latency and sleeps for its configured interval between ticks.+3. The scheduler initializes a first-run watermark per workspace/project and+ records a per-session claim before scheduled LLM work. Historical sessions are+ not reviewed automatically on upgrade, and failed scheduled reviews are not+ retried forever. Manual auto-improve remains the catch-up path for old or+ failed scheduled sessions.+4. Pending proposal storage must use additive, idempotent migrations that+ preserve all existing wiki files and session/observation rows.+5. Existing installed `CLAUDE.md`/`AGENTS.md` blocks remain valid. Operators pickup newer proactive retrieval guidance by running `ai-memory install-instructions`or asking an agent to refresh the ai-memory routing block. The marker-basedreplacement must remain idempotent.-5. Target-page mutations must pass through proposal staging first and must keep+6. Target-page mutations must pass through proposal staging first and must keepapproval attribution separate from the autonomous`auto_improve` proposal actor.@@ -260,23 +276,24 @@ The exact names can change, but the shape should be explicit and conservative:require_approval = false # true leaves proposals pending for manual reviewmin_observations = 8min_session_duration_secs = 120-min_confidence = 0.75 # tune before any future unattended trigger design+min_confidence = 0.75max_input_tokens = 24000max_proposals_per_run = 5include_raw_fallback = falseproposal_actor = "auto_improve"pending_path = "_pending/auto-improve"-```-Future scheduled maintenance settings should live in a separate config section-once that scheduler exists; do not copy unsupported `auto_improve.maintenance`-keys into current configs.+[auto_improve.scheduler]+enabled = true # false disables background review only+interval_secs = 3600 # 0 disables background review only+max_sessions_per_tick = 1+min_session_age_secs = 600+```-A future unattended session-end loop must not ship until manually-triggered-auto-improvement has enough real usage to calibrate prompt quality and-false-positive rates. The confidence threshold should remain configurable-because real projects vary; initial values should be chosen from applied-proposals against existing deployed wikis, not from prompt intuition alone.+`[auto_improve.scheduler]` controls whether and how often the server launches+background review. `[auto_improve] require_approval` controls whether validated+proposals are applied automatically or left pending. They intentionally do not+imply each other.## Proposal Format@@ -314,15 +331,16 @@ or confidence below the configured threshold.## Pending Review UX-The first production UX is explicit and audit-gated. CLI/admin/MCP-auto-improvement records validated pending proposals, then auto-approves them by-default through the wiki mutation path. With `require_approval = true`,+The first production UX is explicit and audit-gated. The scheduler and+CLI/admin/MCP manual runs record validated pending proposals, then auto-approve+them by default through the wiki mutation path. With `require_approval = true`,`pending-writes` applies or rejects them later.| Command or route | Purpose ||---|---|-| `ai-memory auto-improve --session-id <id>` | Review one session and apply validated proposals through the auto-improvement approval path. |-| `memory_auto_improve` | Review the latest completed session or a named session and apply validated proposals through the same path. |+| Background scheduler | Reviews newly completed sessions after the first-run watermark and applies or stages validated proposals according to approval policy. |+| `ai-memory auto-improve --session-id <id>` | Manually review one session and apply or stage validated proposals through the auto-improvement approval path. |+| `memory_auto_improve` | Manually review the latest completed session or a named session and apply or stage validated proposals through the same path. || `ai-memory curator` | Rule-based, report-only maintenance review. || `ai-memory curator --stage` | Stage exactly one curator report page for pending-writes approval. || `ai-memory pending-writes list` | Show staged wiki changes. |@@ -419,17 +437,23 @@ Tests:7. Approval/audit metadata preserves `auto_improve` proposal attribution and theapproving actor separately.-### Phase 3: Optional Session-End Trigger+### Phase 3: Background Scheduler-Add a background trigger behind config. It should run after the normal session-page is written and never block the hook response.+Status: implemented as a server-side scheduler, not a SessionEnd hook trigger.+The scheduler is enabled by default when an LLM provider exists, sleeps for its+configured interval, and reviews only newly completed sessions after the+persisted first-run watermark. It records a per-session claim before calling the+LLM, so scheduled review is at-most-once per completed session unless an admin+reruns auto-improve manually.Tests:-1. Disabled config does nothing.-2. Enabled config stages proposals after session-end.-3. Saturated or failed review leaves normal session-end behavior intact.-4. Reports include model/provider, scope, proposals, rejections, and errors.+1. Disabled scheduler config does nothing while manual runs still work.+2. Enabled scheduler reviews only post-watermark sessions.+3. Saturated or failed review leaves normal session-end behavior intact and does+ not retry the same session forever.+4. Run rows include model/provider, scope, proposals, rejections, config, and+ scheduler trigger metadata.### Phase 4: Maintenance Curator@@ -454,10 +478,6 @@ Tests:4. The minimum confidence threshold should be configurable and calibrated withapplied proposals on real projects before any future unattended trigger is considered.-## Remaining Open Question--Should unattended SessionEnd auto-improvement ever be enabled by default?-## Current ConclusionHermes validates the idea, but also shows why the boundaries matter. The useful@@ -465,7 +485,8 @@ part is not that the agent can write memory by itself. The useful part is abounded, observable, reviewable loop that turns repeated work into durableknowledge while keeping active task execution isolated.-For ai-memory, the current correct boundary is pending proposal storage under-`_pending/auto-improve/` plus approval/rejection commands. Unattended-SessionEnd mutation should remain out of scope until manually-triggered applied-proposals prove high signal in real deployments.+For ai-memory, the current correct boundary is scheduled review plus pending+proposal storage under `_pending/auto-improve/`. Approval policy is separate:+default auto-approval keeps the wiki compiling forward, while+`require_approval = true` gives admins a human queue without disabling the+learning loop.diff --git a/docs/design-decisions.md b/docs/design-decisions.mdindex cf9ad552..deeb63c5 100644--- a/docs/design-decisions.md+++ b/docs/design-decisions.md@@ -140,11 +140,13 @@ Decay/forget runs as a separate `memory_forget_sweep` job: applies the retentionAuto-improvement work stays separate from normal session consolidation. Thereviewer notes and staged design are in[`docs/auto-improvement-loop.md`](auto-improvement-loop.md). The short version:-learning review is default-available when an LLM provider is configured, and-manual CLI/admin/MCP runs apply validated proposals through the auto-improvement-approval path by default. Admins can opt into manual review with-`[auto_improve] require_approval = true`. All writes remain scoped through the-shared resolver/auth paths and must not mutate the active agent context mid-turn.+learning review is scheduled for newly completed sessions when an LLM provider+is configured, and manual CLI/admin/MCP runs remain available for catch-up or+targeted reruns. Scheduling and approval are separate: `[auto_improve.scheduler]`+controls background review, while `[auto_improve] require_approval = true` keeps+scheduled and manual proposals pending for human approval instead of applying+them automatically. All writes remain scoped through the shared resolver/auth+paths and must not mutate the active agent context mid-turn.## 9. Cross-agent handoff@@ -184,7 +186,7 @@ basic-memory has ~25 tools, agentmemory has 53. Both have user confusion as a re| `memory_handoff_accept` | Fetch + ack the latest open handoff | destructive || `memory_handoff_cancel` | Mark an exact mistakenly-created open handoff expired | destructive || `memory_consolidate` | LLM-driven page rewrite (`multi_page=true` for atomic fan-out) | destructive |-| `memory_auto_improve` | Learning review that applies validated wiki edits through the auto-improvement approval path; manual-review opt-in keeps proposals pending | write |+| `memory_auto_improve` | Manual learning review for a completed session; the server also schedules review for new sessions, and manual-review opt-in keeps proposals pending | write || `memory_write_page` | Write durable wiki knowledge on explicit user request | destructive || `memory_read_page` | Read a full page body by exact path or top search hit | read-only || `memory_delete_page` | Delete a single exact-path page with admission hooks | destructive |diff --git a/docs/usage.md b/docs/usage.mdindex 0b9a3ec1..6e5e8d85 100644--- a/docs/usage.md+++ b/docs/usage.md@@ -54,7 +54,7 @@ the wiki without you naming tools explicitly.| "Save context for the next session" | `memory_handoff_begin` | Writes a terse session-end handoff with open questions and next steps. Do not use for status or briefing requests. || "Discard that handoff" / "I created a handoff by mistake" | `memory_handoff_cancel` | Marks an exact open handoff id expired before the next session can consume it. || "Consolidate this session" | `memory_consolidate` | Manually runs LLM consolidation. Also runs on PreCompact, and at session end only when `AI_MEMORY_CONSOLIDATE_ON_SESSION_END` is set (off by default; session end otherwise writes a rule-based summary page). |-| "What did we learn from this session?" / "what memory should we add?" | `memory_auto_improve` | Reviews the latest completed session by default and applies validated edits through the auto-improvement approval path. Admins can set `[auto_improve] require_approval = true` to leave proposals in pending-writes for manual review. |+| "What did we learn from this session?" / "what memory should we add?" | `memory_auto_improve` | Manually reviews the latest completed session by default. The server also runs scheduled auto-improvement for new completed sessions when an LLM is configured. `[auto_improve.scheduler] enabled = false` disables automatic review; `[auto_improve] require_approval = true` leaves scheduled and manual proposals in pending-writes for review. || "Remember this permanently" / "add an annotation" | `memory_write_page` | Writes durable wiki knowledge; not a single-use handoff. || "Delete this page" / "remove the note about X" | `memory_delete_page` | Removes a page by exact path. Pass `workspace` + `project` together when the page lives in a sibling workspace, so a project name shared between workspaces never silently routes the delete to the wrong slot. || "Audit the wiki" / "any contradictions?" | `memory_lint` | Runs stale-page, contradiction, and rule-suggestion checks. |