Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
M7a: LLM-driven single-page session consolidation
AkitaOnRails187794d24bc6
diff --git a/Cargo.lock b/Cargo.lockindex 7ffee8df..16d2f265 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -64,6 +64,17 @@ name = "ai-memory-consolidate"version = "0.1.0"dependencies = ["ai-memory-core",+ "ai-memory-llm",+ "ai-memory-store",+ "ai-memory-wiki",+ "anyhow",+ "schemars",+ "serde",+ "serde_json",+ "tempfile",+ "thiserror 2.0.18",+ "tokio",+ "tracing",][[package]]@@ -118,8 +129,11 @@ dependencies = [name = "ai-memory-mcp"version = "0.1.0"dependencies = [+ "ai-memory-consolidate","ai-memory-core",+ "ai-memory-llm","ai-memory-store",+ "ai-memory-wiki","anyhow","axum","rmcp",diff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rsindex 32b57eff..517c2550 100644--- a/crates/ai-memory-cli/src/commands/serve.rs+++ b/crates/ai-memory-cli/src/commands/serve.rs@@ -1,6 +1,7 @@//! `ai-memory serve` — MCP server with optional filesystem watcher.use ai_memory_hooks::{HookState, hook_router};+use ai_memory_llm::provider_from_env;use ai_memory_mcp::AiMemoryServer;use ai_memory_store::Store;use ai_memory_wiki::{WatcherHandle, Wiki};@@ -48,7 +49,18 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {Some(WatcherHandle::start(wiki.clone(), ws, proj)?)};- let server = AiMemoryServer::new(store.reader.clone(), store.writer.clone(), ws, proj);+ let mut server = AiMemoryServer::new(store.reader.clone(), store.writer.clone(), ws, proj);+ if let Some(cfg) = provider_from_env()? {+ let llm = ai_memory_llm::build_provider(cfg).context("building LLM provider from env")?;+ info!(+ provider = llm.name(),+ model = llm.model(),+ "memory_consolidate tool enabled",+ );+ server = server.with_consolidator(wiki.clone(), llm);+ } else {+ info!("AI_MEMORY_LLM_PROVIDER unset; memory_consolidate disabled");+ }match args.transport {TransportKind::Stdio => {diff --git a/crates/ai-memory-consolidate/Cargo.toml b/crates/ai-memory-consolidate/Cargo.tomlindex cf1f1cb0..4acb7e57 100644--- a/crates/ai-memory-consolidate/Cargo.toml+++ b/crates/ai-memory-consolidate/Cargo.toml@@ -10,6 +10,19 @@ description = "Karpathy-style ingest / query / lint consolidation pipeline."[dependencies]ai-memory-core.workspace = true+ai-memory-store.workspace = true+ai-memory-wiki.workspace = true+ai-memory-llm.workspace = true+anyhow.workspace = true+thiserror.workspace = true+serde.workspace = true+serde_json.workspace = true+schemars.workspace = true+tokio.workspace = true+tracing.workspace = true++[dev-dependencies]+tempfile.workspace = true[lints]workspace = truediff --git a/crates/ai-memory-consolidate/src/consolidator.rs b/crates/ai-memory-consolidate/src/consolidator.rsnew file mode 100644index 00000000..10e3adec--- /dev/null+++ b/crates/ai-memory-consolidate/src/consolidator.rs@@ -0,0 +1,268 @@+//! Single-page session consolidator.+//!+//! Reads the observation log for a session, asks the configured LLM+//! for an updated [`ConsolidatedPage`], then writes it via+//! [`Wiki::write_page`] so the supersession chain + git auto-commit+//! kicks in automatically.++use std::sync::Arc;++use ai_memory_core::{+ Observation, ObservationKind, PagePath, ProjectId, SessionId, Tier, WorkspaceId,+};+use ai_memory_llm::{ChatMessage, ChatRequest, LlmError, LlmProvider, Role, complete_structured};+use ai_memory_store::{ReaderPool, WriterHandle};+use ai_memory_wiki::{Wiki, WritePageRequest};+use thiserror::Error;+use tracing::{debug, info};++use crate::types::{ConsolidatedPage, ConsolidationOutcome};++/// Errors raised by the consolidator.+#[derive(Debug, Error)]+#[non_exhaustive]+pub enum ConsolidatorError {+ /// Domain-level error (e.g. invalid `PagePath`).+ #[error(transparent)]+ Memory(#[from] ai_memory_core::MemoryError),++ /// Underlying store error.+ #[error(transparent)]+ Store(#[from] ai_memory_store::StoreError),++ /// Underlying wiki error.+ #[error(transparent)]+ Wiki(#[from] ai_memory_wiki::WikiError),++ /// Underlying LLM error.+ #[error(transparent)]+ Llm(#[from] LlmError),++ /// JSON error.+ #[error("serde: {0}")]+ Serde(String),++ /// Session was not found.+ #[error("session not found: {0}")]+ SessionNotFound(SessionId),++ /// Session had no observations to consolidate.+ #[error("session {0} has no observations")]+ EmptySession(SessionId),+}++impl From<serde_json::Error> for ConsolidatorError {+ fn from(value: serde_json::Error) -> Self {+ Self::Serde(value.to_string())+ }+}++/// Result alias used by the consolidator.+pub type ConsolidatorResult<T> = Result<T, ConsolidatorError>;++/// Karpathy-style single-page consolidator. Holds handles to the+/// store, wiki, and LLM provider so it can be reused across many+/// `consolidate_session` calls.+pub struct Consolidator {+ reader: ReaderPool,+ writer: WriterHandle,+ wiki: Wiki,+ llm: Arc<dyn LlmProvider>,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+}++impl Consolidator {+ /// Construct a consolidator. Caller is responsible for selecting+ /// the LLM provider via the `ai-memory-llm` factory.+ #[must_use]+ pub fn new(+ reader: ReaderPool,+ writer: WriterHandle,+ wiki: Wiki,+ llm: Arc<dyn LlmProvider>,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ ) -> Self {+ Self {+ reader,+ writer,+ wiki,+ llm,+ workspace_id,+ project_id,+ }+ }++ /// Consolidate a single session into a refreshed+ /// `sessions/<id>.md` page.+ ///+ /// # Errors+ /// Returns [`ConsolidatorError`] for any store, wiki, or LLM+ /// failure.+ pub async fn consolidate_session(+ &self,+ session_id: SessionId,+ dry_run: bool,+ ) -> ConsolidatorResult<ConsolidationOutcome> {+ let observations = self.reader.observations_for_session(session_id).await?;+ if observations.is_empty() {+ return Err(ConsolidatorError::EmptySession(session_id));+ }++ let path = PagePath::new(format!("sessions/{session_id}.md"))?;+ let current_body = self+ .wiki+ .read_page(&path)+ .map(|md| md.body)+ .unwrap_or_default();+ let request = build_request(session_id, &observations, ¤t_body);+ debug!(+ session = %session_id,+ provider = self.llm.name(),+ model = self.llm.model(),+ "consolidating session"+ );+ let page: ConsolidatedPage = complete_structured(&*self.llm, request).await?;++ if dry_run {+ return Ok(ConsolidationOutcome {+ path,+ dry_run: true,+ new_title: page.title,+ new_body_markdown: page.body_markdown,+ page_id: None,+ tags: page.tags,+ });+ }++ let frontmatter = build_frontmatter(&page);+ let id = self+ .wiki+ .write_page(WritePageRequest {+ workspace_id: self.workspace_id,+ project_id: self.project_id,+ path: path.clone(),+ frontmatter,+ body: page.body_markdown.clone(),+ tier: Tier::Episodic,+ pinned: false,+ })+ .await?;+ // Auto-commit the result so the supersession lands in git.+ let _ = self+ .wiki+ .commit_all(&format!(+ "consolidate(session {}): {}",+ short_id(&session_id.to_string()),+ page.title.chars().take(60).collect::<String>(),+ ))+ .map_err(|e| {+ tracing::warn!(error = %e, "consolidate auto-commit failed");+ e+ });+ info!(+ session = %session_id,+ page = %id,+ "session consolidated via LLM",+ );+ Ok(ConsolidationOutcome {+ path,+ dry_run: false,+ new_title: page.title,+ new_body_markdown: page.body_markdown,+ page_id: Some(id),+ tags: page.tags,+ })+ }++ /// Borrow the underlying writer (used by the MCP tool to ack the+ /// consolidate operation in the audit log).+ #[must_use]+ pub fn writer(&self) -> &WriterHandle {+ &self.writer+ }+}++fn build_request(+ session_id: SessionId,+ observations: &[Observation],+ current_body: &str,+) -> ChatRequest {+ let mut buf = String::new();+ buf.push_str("Session id: ");+ buf.push_str(&session_id.to_string());+ buf.push_str("\nObservations (in order):\n\n");+ for o in observations {+ buf.push_str(&format!("- {} | {}\n", o.kind.as_str(), one_line(&o.title)));+ if !o.body.trim().is_empty() {+ buf.push_str(&format!(" body: {}\n", one_line(&o.body)));+ }+ }+ if !current_body.trim().is_empty() {+ buf.push_str("\nCurrent (heuristic) page body:\n\n```\n");+ buf.push_str(current_body);+ buf.push_str("\n```\n");+ }++ ChatRequest {+ system: Some(SYSTEM_PROMPT.into()),+ messages: vec![ChatMessage {+ role: Role::User,+ content: buf,+ }],+ max_tokens: 1500,+ temperature: Some(0.2),+ }+}++fn build_frontmatter(page: &ConsolidatedPage) -> serde_json::Value {+ let mut map = serde_json::Map::new();+ map.insert(+ "title".into(),+ serde_json::Value::String(page.title.clone()),+ );+ map.insert("tier".into(), serde_json::Value::String("episodic".into()));+ if !page.tags.is_empty() {+ let tags = page+ .tags+ .iter()+ .map(|t| serde_json::Value::String(t.clone()))+ .collect();+ map.insert("tags".into(), serde_json::Value::Array(tags));+ }+ map.insert("consolidated".into(), serde_json::Value::Bool(true));+ serde_json::Value::Object(map)+}++fn one_line(s: &str) -> String {+ s.lines()+ .map(str::trim)+ .filter(|l| !l.is_empty())+ .take(3)+ .collect::<Vec<_>>()+ .join(" / ")+ .chars()+ .take(240)+ .collect()+}++fn short_id(s: &str) -> String {+ s.chars().take(8).collect()+}++/// Suppress the unused-variant lint for now; consumers will use+/// [`ObservationKind`] via the observations parameter.+const _OBSERVATION_KIND: Option<ObservationKind> = None;++const SYSTEM_PROMPT: &str = "You are the maintainer of a Karpathy-style LLM wiki for a \+software engineer. You receive the chronological observation log of one coding-agent \+session plus the current heuristic page body. Compile a clean, durable markdown page \+that future agents and the user can read to recover context.\n\nRules:\n\+1. Title: short, descriptive (<= 80 chars). No filler.\n\+2. Body: well-formed markdown. Use sections (## Heading) when useful.\n\+3. Focus on decisions made, problems encountered, code/file references, and open \+ questions.\n\+4. Do NOT include redundant per-tool-call detail. Aggregate.\n\+5. Do NOT echo timestamps or session ids (frontmatter already has them).\n\+6. Tags: 0-5 short kebab-case tags surfaced to frontmatter.\n";diff --git a/crates/ai-memory-consolidate/src/lib.rs b/crates/ai-memory-consolidate/src/lib.rsindex 77cb4ea7..c2b5280f 100644--- a/crates/ai-memory-consolidate/src/lib.rs+++ b/crates/ai-memory-consolidate/src/lib.rs@@ -1,5 +1,15 @@//! Karpathy "LLM Wiki" consolidation pipeline.//!-//! Implements the three operations from the gist: ingest (write fan-out),-//! query (hierarchical retrieval), and lint (contradiction & orphan-//! detection). Plus the retention/decay sweep. Lands in milestones M7 / M8.+//! M7a delivers the single-page variant: rewrite one+//! `sessions/<id>.md` page from raw observations via an LLM. The+//! store's sha256-equality short-circuit + supersession chain means+//! the rewrite is a *version*, not a destructive overwrite —+//! exactly the Karpathy pattern.+//!+//! M7b extends this to multi-page atomic fan-out.++pub mod consolidator;+pub mod types;++pub use consolidator::{Consolidator, ConsolidatorError, ConsolidatorResult};+pub use types::{ConsolidatedPage, ConsolidationOutcome};diff --git a/crates/ai-memory-consolidate/src/types.rs b/crates/ai-memory-consolidate/src/types.rsnew file mode 100644index 00000000..727de8ce--- /dev/null+++ b/crates/ai-memory-consolidate/src/types.rs@@ -0,0 +1,37 @@+//! Public-facing consolidation types.++use ai_memory_core::{PageId, PagePath};+use schemars::JsonSchema;+use serde::{Deserialize, Serialize};++/// JSON-schema-validated structured output from the LLM. The Karpathy+/// wiki pattern is "compile then keep current"; this is what one+/// compile step produces for a single page.+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]+pub struct ConsolidatedPage {+ /// Page title; rendered as the first H1 by the wiki layer.+ pub title: String,+ /// Markdown body (no frontmatter; the wiki layer adds that).+ pub body_markdown: String,+ /// Up to ~5 short tags surfaced into the page's frontmatter.+ #[serde(default)]+ pub tags: Vec<String>,+}++/// Outcome of a single consolidation call.+#[derive(Debug, Clone, Serialize)]+pub struct ConsolidationOutcome {+ /// Path of the page that was (or would be) written.+ pub path: PagePath,+ /// Whether the call ran in dry-run mode.+ pub dry_run: bool,+ /// New title.+ pub new_title: String,+ /// New body. Hidden when content has not changed.+ pub new_body_markdown: String,+ /// Identifier of the page that is now `is_latest = 1`. `None` on+ /// dry-run.+ pub page_id: Option<PageId>,+ /// Tags applied to the page.+ pub tags: Vec<String>,+}diff --git a/crates/ai-memory-llm/src/factory.rs b/crates/ai-memory-llm/src/factory.rsindex 480b27a6..62d94028 100644--- a/crates/ai-memory-llm/src/factory.rs+++ b/crates/ai-memory-llm/src/factory.rs@@ -37,6 +37,53 @@ pub struct ProviderConfig {pub base_url: Option<String>,}+/// Build a [`ProviderConfig`] from the environment.+///+/// Reads `AI_MEMORY_LLM_PROVIDER`, `AI_MEMORY_LLM_MODEL`,+/// `AI_MEMORY_LLM_BASE_URL`, and the appropriate API key+/// (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `LLM_API_KEY`).+/// Returns `Ok(None)` when `AI_MEMORY_LLM_PROVIDER` is unset — that+/// is the canonical "no LLM features" path.+///+/// # Errors+/// Returns [`LlmError::NotConfigured`] when the provider env var is+/// set to an unknown value or when the model env var is missing.+pub fn provider_from_env() -> LlmResult<Option<ProviderConfig>> {+ let provider = match std::env::var("AI_MEMORY_LLM_PROVIDER") {+ Ok(s) => match s.as_str() {+ "anthropic" => ProviderChoice::Anthropic,+ "openai" => ProviderChoice::OpenAi,+ "openai-compat" | "openai_compat" => ProviderChoice::OpenAiCompat,+ other => {+ return Err(LlmError::NotConfigured(format!(+ "AI_MEMORY_LLM_PROVIDER={other} is not one of anthropic|openai|openai-compat"+ )));+ }+ },+ Err(_) => return Ok(None),+ };+ let model = std::env::var("AI_MEMORY_LLM_MODEL")+ .map_err(|_| LlmError::NotConfigured("AI_MEMORY_LLM_MODEL".into()))?;+ let base_url = std::env::var("AI_MEMORY_LLM_BASE_URL").ok();+ let api_key = match provider {+ ProviderChoice::Anthropic => std::env::var("ANTHROPIC_API_KEY")+ .ok()+ .map(secrecy::SecretString::from),+ ProviderChoice::OpenAi => std::env::var("OPENAI_API_KEY")+ .ok()+ .map(secrecy::SecretString::from),+ ProviderChoice::OpenAiCompat => std::env::var("LLM_API_KEY")+ .ok()+ .map(secrecy::SecretString::from),+ };+ Ok(Some(ProviderConfig {+ provider,+ model,+ api_key,+ base_url,+ }))+}+/// Construct an `Arc<dyn LlmProvider>` matching the config.////// # Errorsdiff --git a/crates/ai-memory-llm/src/lib.rs b/crates/ai-memory-llm/src/lib.rsindex 5f528ec6..b40d18f5 100644--- a/crates/ai-memory-llm/src/lib.rs+++ b/crates/ai-memory-llm/src/lib.rs@@ -29,7 +29,7 @@ pub mod types;pub use anthropic::AnthropicProvider;pub use error::{LlmError, LlmResult};-pub use factory::{ProviderChoice, ProviderConfig, build_provider};+pub use factory::{ProviderChoice, ProviderConfig, build_provider, provider_from_env};pub use openai::OpenAiProvider;pub use openai_compat::OpenAiCompatProvider;pub use provider::{LlmProvider, complete_structured};diff --git a/crates/ai-memory-mcp/Cargo.toml b/crates/ai-memory-mcp/Cargo.tomlindex b648942c..96c5836a 100644--- a/crates/ai-memory-mcp/Cargo.toml+++ b/crates/ai-memory-mcp/Cargo.toml@@ -10,7 +10,10 @@ description = "MCP server transport and tool router for ai-memory."[dependencies]ai-memory-core.workspace = true+ai-memory-consolidate.workspace = true+ai-memory-llm.workspace = trueai-memory-store.workspace = true+ai-memory-wiki.workspace = trueanyhow.workspace = truethiserror.workspace = trueserde.workspace = truediff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rsindex ac7c92d8..024a2538 100644--- a/crates/ai-memory-mcp/src/server.rs+++ b/crates/ai-memory-mcp/src/server.rs@@ -1,7 +1,13 @@//! [`AiMemoryServer`] — the MCP server skeleton + tool router.-use ai_memory_core::{AgentKind, NewHandoff, ProjectId, WorkspaceId};+use std::str::FromStr;+use std::sync::Arc;++use ai_memory_consolidate::Consolidator;+use ai_memory_core::{AgentKind, NewHandoff, ProjectId, SessionId, WorkspaceId};+use ai_memory_llm::LlmProvider;use ai_memory_store::{ReaderPool, WriterHandle};+use ai_memory_wiki::Wiki;use rmcp::handler::server::router::tool::ToolRouter;use rmcp::handler::server::wrapper::Parameters;use rmcp::model::{@@ -26,6 +32,9 @@ pub struct AiMemoryServer {workspace_id: WorkspaceId,project_id: ProjectId,default_limit: usize,+ /// Optional LLM consolidator. When `None`, `memory_consolidate`+ /// returns a "not configured" error.+ consolidator: Option<Arc<Consolidator>>,// Read by the `#[tool_handler]` macro expansion; rustc's dead-code// analysis can't see that, so the lint must be allowed explicitly.#[allow(dead_code)]@@ -59,6 +68,15 @@ struct StatusResponse {counts: ai_memory_store::StatusCounts,}+#[derive(Debug, Serialize, Deserialize, schemars::JsonSchema)]+struct ConsolidateArgs {+ /// UUID of the session to consolidate.+ session_id: String,+ /// If true, preview without writing. Default false.+ #[serde(default)]+ dry_run: Option<bool>,+}+#[derive(Debug, Serialize, Deserialize, schemars::JsonSchema)]struct HandoffBeginArgs {/// Short prose summary of where the session left off.@@ -102,10 +120,27 @@ impl AiMemoryServer {workspace_id,project_id,default_limit: 10,+ consolidator: None,tool_router: Self::tool_router(),}}+ /// Attach an LLM-backed consolidator. Without this, the+ /// `memory_consolidate` tool errors with "not configured".+ #[must_use]+ pub fn with_consolidator(mut self, wiki: Wiki, llm: Arc<dyn LlmProvider>) -> Self {+ let consolidator = Consolidator::new(+ self.reader.clone(),+ self.writer.clone(),+ wiki,+ llm,+ self.workspace_id,+ self.project_id,+ );+ self.consolidator = Some(Arc::new(consolidator));+ self+ }+/// Full-text search the wiki via FTS5. Returns up to `limit` hits with/// HTML-marked snippets and a rank score.#[tool(description = "Full-text search the long-term memory wiki via FTS5. \@@ -144,6 +179,32 @@ impl AiMemoryServer {ok_json(&response)}+ /// LLM-driven consolidation of a session into a refreshed+ /// `sessions/<id>.md` page (M7a single-page variant).+ #[tool(description = "LLM-driven consolidation: rewrite the \+ sessions/<id>.md page for the given session_id using the \+ observation log + the current heuristic body. Off by default; \+ requires AI_MEMORY_LLM_PROVIDER / AI_MEMORY_LLM_MODEL set on \+ the server. Pass dry_run=true to preview without writing.")]+ async fn memory_consolidate(+ &self,+ Parameters(args): Parameters<ConsolidateArgs>,+ ) -> Result<CallToolResult, McpError> {+ let Some(consolidator) = self.consolidator.as_ref() else {+ return Err(McpError::internal_error(+ "memory_consolidate not configured (set AI_MEMORY_LLM_PROVIDER + AI_MEMORY_LLM_MODEL)",+ None,+ ));+ };+ let session_id = SessionId::from_str(&args.session_id)+ .map_err(|e| McpError::internal_error(e.to_string(), None))?;+ let outcome = consolidator+ .consolidate_session(session_id, args.dry_run.unwrap_or(false))+ .await+ .map_err(|e| McpError::internal_error(e.to_string(), None))?;+ ok_json(&outcome)+ }+/// Create a handoff snapshot for the next agent CLI.#[tool(description = "Record a cross-agent handoff snapshot. Call this \before quitting one CLI so the next one (e.g. Codex picking up \