Skip to content

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.lock
index 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.rs
index 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.toml
index 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 = true
diff --git a/crates/ai-memory-consolidate/src/consolidator.rs b/crates/ai-memory-consolidate/src/consolidator.rs
new file mode 100644
index 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, &current_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.rs
index 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.rs
new file mode 100644
index 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.rs
index 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.
///
/// # Errors
diff --git a/crates/ai-memory-llm/src/lib.rs b/crates/ai-memory-llm/src/lib.rs
index 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.toml
index 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 = true
ai-memory-store.workspace = true
+ai-memory-wiki.workspace = true
anyhow.workspace = true
thiserror.workspace = true
serde.workspace = true
diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rs
index 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 \