Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(consolidate): add slot write regimes
FSTech Digital3268f220c682
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 73be45d9..e1df6a45 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Added+- `_slots/*.md` pages can now declare `slot_kind: state` or+ `slot_kind: invariant` frontmatter. `state` remains the default for existing+ slots; `invariant` marks high-resistance project context or preferences that+ consolidation should not rewrite unless observations directly contradict the+ existing slot content.++### Fixed+- Page upserts now treat frontmatter/title/tier/pinned changes as real page+ updates instead of short-circuiting solely on unchanged body text, keeping the+ SQLite index consistent with markdown frontmatter-only edits.+## [0.6.1] - 2026-05-28### Addeddiff --git a/crates/ai-memory-consolidate/src/consolidator.rs b/crates/ai-memory-consolidate/src/consolidator.rsindex 42cba6e4..c8033438 100644--- a/crates/ai-memory-consolidate/src/consolidator.rs+++ b/crates/ai-memory-consolidate/src/consolidator.rs@@ -14,7 +14,7 @@ use ai_memory_wiki::{Wiki, WritePageRequest};use thiserror::Error;use tracing::{debug, info};-use crate::types::{ConsolidatedBatch, ConsolidatedPage, ConsolidationOutcome};+use crate::types::{ConsolidatedBatch, ConsolidatedPage, ConsolidationOutcome, SlotKind};/// Errors raised by the consolidator.#[derive(Debug, Error)]@@ -202,6 +202,54 @@ impl Consolidator {self.llm.clone()}+ fn should_skip_high_resistance_slot_update(+ &self,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ req: &WritePageRequest,+ ) -> ConsolidatorResult<bool> {+ if !is_slot_path(&req.path) {+ return Ok(false);+ }+ let existing = match self.wiki.read_page(workspace_id, project_id, &req.path) {+ Ok(md) => Some(md.frontmatter),+ Err(ai_memory_wiki::WikiError::Io(err))+ if err.kind() == std::io::ErrorKind::NotFound =>+ {+ None+ }+ Err(err) => return Err(err.into()),+ };+ Ok(should_skip_high_resistance_slot_update_from_frontmatter(+ &req.path,+ existing.as_ref(),+ &req.frontmatter,+ ))+ }++ async fn slot_snapshots(+ &self,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ ) -> ConsolidatorResult<Vec<SlotSnapshot>> {+ let briefing = self+ .reader+ .briefing_for_project(workspace_id, project_id, 100)+ .await?;+ let mut slots = Vec::with_capacity(briefing.slots.len());+ for slot in briefing.slots {+ let path = PagePath::new(slot.path)?;+ let md = self.wiki.read_page(workspace_id, project_id, &path)?;+ slots.push(SlotSnapshot {+ path: path.as_str().to_string(),+ title: slot.title,+ slot_kind: slot_kind_from_frontmatter(&md.frontmatter),+ body: md.body,+ });+ }+ Ok(slots)+ }+/// M7b multi-page consolidation: ask the LLM for a batch of page/// updates spanning sessions/, concepts/, decisions/, then write/// them all atomically (one SQL transaction).@@ -225,7 +273,8 @@ impl Consolidator {.session_project_ids(session_id).await?.unwrap_or((self.workspace_id, self.project_id));- let request = build_batch_request(session_id, &observations);+ let slots = self.slot_snapshots(ws, proj).await?;+ let request = build_batch_request_with_slots(session_id, &observations, &slots);debug!(session = %session_id,provider = self.llm.name(),@@ -238,6 +287,13 @@ impl Consolidator {let mut outcomes_preview = Vec::with_capacity(batch.updates.len());for upd in &batch.updates {let (req, outcome) = build_update(ws, proj, upd, dry_run)?;+ if self.should_skip_high_resistance_slot_update(ws, proj, &req)? {+ debug!(+ path = %req.path.as_str(),+ "skipping invariant slot update without explicit invariant contradiction signal",+ );+ continue;+ }requests.push(req);outcomes_preview.push(outcome);}@@ -317,6 +373,12 @@ fn build_update(),);}+ if is_slot_path(&path) {+ fm.insert(+ "slot_kind".into(),+ serde_json::Value::String(upd.slot_kind.as_str().into()),+ );+ }fm.insert("consolidated".into(), serde_json::Value::Bool(true));let req = WritePageRequest {@@ -349,11 +411,53 @@ const fn tier_as_str(t: Tier) -> &'static str {}}+fn is_slot_path(path: &PagePath) -> bool {+ path.as_str().starts_with("_slots/")+}++fn slot_kind_from_frontmatter(frontmatter: &serde_json::Value) -> SlotKind {+ match frontmatter+ .get("slot_kind")+ .and_then(serde_json::Value::as_str)+ {+ Some("invariant") => SlotKind::Invariant,+ _ => SlotKind::State,+ }+}++#[derive(Debug, Clone)]+struct SlotSnapshot {+ path: String,+ title: String,+ slot_kind: SlotKind,+ body: String,+}++fn should_skip_high_resistance_slot_update_from_frontmatter(+ path: &PagePath,+ existing_frontmatter: Option<&serde_json::Value>,+ incoming_frontmatter: &serde_json::Value,+) -> bool {+ is_slot_path(path)+ && existing_frontmatter+ .map(|fm| slot_kind_from_frontmatter(fm) == SlotKind::Invariant)+ .unwrap_or(false)+ && slot_kind_from_frontmatter(incoming_frontmatter) != SlotKind::Invariant+}+/// Build the exact ChatRequest the consolidator sends for batch/// multi-page consolidation. Exposed so off-tree A/B harnesses/// (e.g. `evals/`) can exercise the same workload against/// alternative providers without duplicating the prompt.pub fn build_batch_request(session_id: SessionId, observations: &[Observation]) -> ChatRequest {+ build_batch_request_with_slots(session_id, observations, &[])+}++fn build_batch_request_with_slots(+ session_id: SessionId,+ observations: &[Observation],+ slots: &[SlotSnapshot],+) -> ChatRequest {let mut buf = String::new();buf.push_str("You are compiling a Karpathy-style multi-page wiki update. Given the \@@ -372,12 +476,33 @@ pub fn build_batch_request(session_id: SessionId, observations: &[Observation])buf.push_str(&format!(" body: {}\n", one_line(&o.body)));}}+ if !slots.is_empty() {+ buf.push_str("\nCurrent `_slots/` pages (for write-regime decisions):\n");+ for slot in slots {+ buf.push_str(&format!(+ "- {} | slot_kind={} | title={}\n",+ slot.path,+ slot.slot_kind.as_str(),+ one_line(&slot.title),+ ));+ if !slot.body.trim().is_empty() {+ buf.push_str(" body:\n");+ buf.push_str(&indent_for_prompt(&clip_for_prompt(&slot.body, 1_200)));+ buf.push('\n');+ }+ }+ }buf.push_str("\nProduce up to 5 page updates. Use these path conventions:\n\- sessions/<session_id>.md (episodic, this run's narrative)\n\- concepts/<slug>.md (semantic, evergreen concept pages)\n\- decisions/<short>.md (semantic, ADR-style records)\n\- gotchas/<slug>.md (semantic, failure modes / surprises)\n\+ - _slots/<name>.md (pinned memory slot; use sparingly)\n\+ \nSlot pages have two write regimes. For `_slots/*` updates you may include `slot_kind`:\n\+ - \"state\" (default; mutable current focus, pending items, working context)\n\+ - \"invariant\" (high-resistance project rules, identity, or user preferences)\n\+ Do not emit an update for an existing invariant slot unless the observations directly contradict specific existing content. State slots may be refreshed normally.\n\\nSet `tier` to EXACTLY ONE of these four strings — never an integer, never a synonym:\n\- \"working\" (the live in-progress slice of the session — rarely used here)\n\- \"episodic\" (per-session narrative; the sessions/<id>.md page)\n\@@ -400,7 +525,8 @@ pub fn build_batch_request(session_id: SessionId, observations: &[Observation])- \"tier\" (string) required — one of the four tier strings above\n\- \"kind\" (string) required — one of the four kind strings above\n\- \"tags\" (array of string) required — may be empty `[]`, but the key must be present\n\- No other keys. No `body`, no `content`, no `summary`. Field names \+ - \"slot_kind\" (string) optional — only for `_slots/*`; one of \"state\" or \"invariant\"; omitted means \"state\"\n\+ No other keys except optional `slot_kind` on `_slots/*`. No `body`, no `content`, no `summary`. Field names \are case-sensitive and the `_markdown` suffix matters.\n\\n## Output format (read this carefully)\n\Reply with ONE JSON object matching the ConsolidatedBatch schema, \@@ -519,6 +645,22 @@ fn one_line(s: &str) -> String {.collect()}+fn clip_for_prompt(s: &str, max_chars: usize) -> String {+ let mut chars = s.chars();+ let mut out: String = chars.by_ref().take(max_chars).collect();+ if chars.next().is_some() {+ out.push_str("\n[truncated]");+ }+ out+}++fn indent_for_prompt(s: &str) -> String {+ s.lines()+ .map(|line| format!(" {line}"))+ .collect::<Vec<_>>()+ .join("\n")+}+/// ASCII-slug a rule title for the `_rules/<slug>.md` path.////// Lower-cases, replaces runs of non-`[a-z0-9]` with `-`, trims@@ -602,4 +744,109 @@ mod tests {assert!(slug.len() <= 60);assert!(!slug.ends_with('-'));}++ #[test]+ fn slot_update_defaults_to_state_frontmatter() {+ let update = crate::types::ConsolidatedPageUpdate {+ path: "_slots/current_focus.md".into(),+ tier: Tier::Semantic,+ kind: crate::types::PageKind::Fact,+ title: "Current focus".into(),+ body_markdown: "Ship the slot-kind PR.".into(),+ tags: Vec::new(),+ slot_kind: SlotKind::State,+ };+ let (req, _) = build_update(WorkspaceId::new(), ProjectId::new(), &update, true).unwrap();+ assert_eq!(req.frontmatter["slot_kind"], "state");+ }++ #[test]+ fn slot_update_preserves_explicit_invariant_frontmatter() {+ let update = crate::types::ConsolidatedPageUpdate {+ path: "_slots/project_context.md".into(),+ tier: Tier::Semantic,+ kind: crate::types::PageKind::Fact,+ title: "Project context".into(),+ body_markdown: "This repo uses a markdown wiki as source of truth.".into(),+ tags: Vec::new(),+ slot_kind: SlotKind::Invariant,+ };+ let (req, _) = build_update(WorkspaceId::new(), ProjectId::new(), &update, true).unwrap();+ assert_eq!(req.frontmatter["slot_kind"], "invariant");+ }++ #[test]+ fn invariant_slot_skips_state_rewrite_candidate() {+ let path = PagePath::new("_slots/project_context.md").unwrap();+ let existing = serde_json::json!({"title": "Project context", "slot_kind": "invariant"});+ let incoming = serde_json::json!({"title": "Project context", "slot_kind": "state"});+ assert!(should_skip_high_resistance_slot_update_from_frontmatter(+ &path,+ Some(&existing),+ &incoming,+ ));+ }++ #[test]+ fn invariant_slot_allows_explicit_invariant_rewrite_candidate() {+ let path = PagePath::new("_slots/project_context.md").unwrap();+ let existing = serde_json::json!({"title": "Project context", "slot_kind": "invariant"});+ let incoming = serde_json::json!({"title": "Project context", "slot_kind": "invariant"});+ assert!(!should_skip_high_resistance_slot_update_from_frontmatter(+ &path,+ Some(&existing),+ &incoming,+ ));+ }++ #[test]+ fn non_slot_paths_ignore_slot_kind_guard() {+ let path = PagePath::new("concepts/project-context.md").unwrap();+ let existing = serde_json::json!({"slot_kind": "invariant"});+ let incoming = serde_json::json!({"slot_kind": "state"});+ assert!(!should_skip_high_resistance_slot_update_from_frontmatter(+ &path,+ Some(&existing),+ &incoming,+ ));+ }++ #[test]+ fn missing_slot_kind_defaults_to_state() {+ assert_eq!(+ slot_kind_from_frontmatter(&serde_json::json!({"title": "Pending items"})),+ SlotKind::State,+ );+ }++ #[test]+ fn batch_request_includes_existing_slot_regimes() {+ let session_id = SessionId::new();+ let slots = vec![SlotSnapshot {+ path: "_slots/project_context.md".into(),+ title: "Project context".into(),+ slot_kind: SlotKind::Invariant,+ body: "This is stable unless a later observation contradicts it.".into(),+ }];+ let request = build_batch_request_with_slots(session_id, &[], &slots);+ let prompt = &request.messages[0].content;+ assert!(prompt.contains("Current `_slots/` pages"));+ assert!(prompt.contains("_slots/project_context.md | slot_kind=invariant"));+ assert!(prompt.contains("This is stable unless"));+ }++ #[test]+ fn page_update_deserialisation_defaults_slot_kind_to_state() {+ let update: crate::types::ConsolidatedPageUpdate =+ serde_json::from_value(serde_json::json!({+ "path": "_slots/current_focus.md",+ "tier": "semantic",+ "kind": "fact",+ "title": "Current focus",+ "body_markdown": "Keep the PR narrow.",+ "tags": []+ }))+ .unwrap();+ assert_eq!(update.slot_kind, SlotKind::State);+ }}diff --git a/crates/ai-memory-consolidate/src/lib.rs b/crates/ai-memory-consolidate/src/lib.rsindex adc22dd6..bd18122d 100644--- a/crates/ai-memory-consolidate/src/lib.rs+++ b/crates/ai-memory-consolidate/src/lib.rs@@ -26,4 +26,5 @@ pub use lint::{LintError, LintFinding, LintReport, run_lint};pub use sweep::{EvictedPage, SweepError, SweepReport, run_sweep};pub use types::{ConsolidatedBatch, ConsolidatedPage, ConsolidatedPageUpdate, ConsolidationOutcome, PageKind,+ SlotKind,};diff --git a/crates/ai-memory-consolidate/src/types.rs b/crates/ai-memory-consolidate/src/types.rsindex ba522c10..5d0242e5 100644--- a/crates/ai-memory-consolidate/src/types.rs+++ b/crates/ai-memory-consolidate/src/types.rs@@ -63,6 +63,34 @@ impl PageKind {}}+/// Write-regime hint for `_slots/*.md` pages.+///+/// Slot pages are always pinned, but they do not all want the same+/// consolidation gradient. `State` slots are the mutable working set+/// (current focus, pending items); `Invariant` slots are high-resistance+/// project context or user preferences and should only be rewritten when+/// observations explicitly contradict existing content.+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema, Default)]+#[serde(rename_all = "snake_case")]+pub enum SlotKind {+ /// Stable context or preference. High write resistance.+ Invariant,+ /// Mutable current-state slot. Default for backwards compatibility.+ #[default]+ State,+}++impl SlotKind {+ /// Wire string for serialisation + frontmatter.+ #[must_use]+ pub const fn as_str(self) -> &'static str {+ match self {+ Self::Invariant => "invariant",+ Self::State => "state",+ }+ }+}+/// One update inside a multi-page consolidation batch (M7b).#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]pub struct ConsolidatedPageUpdate {@@ -89,6 +117,11 @@ pub struct ConsolidatedPageUpdate {/// Optional tags surfaced into frontmatter.#[serde(default)]pub tags: Vec<String>,+ /// Write-regime hint for `_slots/*.md` updates. Ignored for non-slot+ /// paths. Defaults to `state` so existing structured outputs keep their+ /// current behaviour.+ #[serde(default)]+ pub slot_kind: SlotKind,}/// Batch produced by [`ConsolidatorMulti`].diff --git a/crates/ai-memory-store/src/ops.rs b/crates/ai-memory-store/src/ops.rsindex 59acf782..8a13150f 100644--- a/crates/ai-memory-store/src/ops.rs+++ b/crates/ai-memory-store/src/ops.rs@@ -160,6 +160,15 @@ pub fn upsert_pages_batch(conn: &mut Connection, pages: &[NewPage]) -> StoreResuOk(out)}+struct ExistingPageVersion {+ id: Vec<u8>,+ body_sha256: Vec<u8>,+ frontmatter_json: String,+ title: String,+ tier: String,+ pinned: i64,+}+fn upsert_page_in_tx(tx: &rusqlite::Transaction<'_>,page: &NewPage,@@ -173,27 +182,41 @@ fn upsert_page_in_tx(let frontmatter_str = serde_json::to_string(&page.frontmatter_json)?;let tier_str = page.tier.as_str();- let existing: Option<(Vec<u8>, Vec<u8>)> = tx+ let existing: Option<ExistingPageVersion> = tx.query_row(- "SELECT id, body_sha256 FROM pages \+ "SELECT id, body_sha256, frontmatter_json, title, tier, pinned FROM pages \WHERE workspace_id = ?1 AND project_id = ?2 AND path = ?3 AND is_latest = 1",params![page.workspace_id.as_bytes(),page.project_id.as_bytes(),page.path.as_str(),],- |row| Ok((row.get(0)?, row.get(1)?)),+ |row| {+ Ok(ExistingPageVersion {+ id: row.get(0)?,+ body_sha256: row.get(1)?,+ frontmatter_json: row.get(2)?,+ title: row.get(3)?,+ tier: row.get(4)?,+ pinned: row.get(5)?,+ })+ },).optional()?;- if let Some((existing_id, existing_sha)) = existing {- if existing_sha == body_sha256 {- return PageId::from_slice(&existing_id).map_err(StoreError::from);+ if let Some(existing) = existing {+ if existing.body_sha256 == body_sha256+ && existing.frontmatter_json == frontmatter_str+ && existing.title == page.title+ && existing.tier == tier_str+ && existing.pinned == i64::from(page.pinned)+ {+ return PageId::from_slice(&existing.id).map_err(StoreError::from);}let new_id = PageId::new();tx.execute("UPDATE pages SET is_latest = 0 WHERE id = ?1",- params![existing_id],+ params![&existing.id],)?;tx.execute("INSERT INTO pages \@@ -210,7 +233,7 @@ fn upsert_page_in_tx(page.body,body_sha256.as_slice(),frontmatter_str,- existing_id,+ &existing.id,i64::from(page.pinned),now,],@@ -1017,6 +1040,37 @@ mod tests {assert_eq!(total, 1, "no duplicate row for unchanged content");}+ #[test]+ fn upsert_page_supersedes_on_frontmatter_change() {+ let (_tmp, mut conn, ws, proj) = fresh_db();+ let mut p1 = page(ws, proj, "_slots/project_context.md", "same body");+ p1.frontmatter_json = serde_json::json!({+ "title": "Project context",+ "slot_kind": "state",+ });+ let id1 = upsert_page(&mut conn, &p1).unwrap();++ let mut p2 = p1.clone();+ p2.frontmatter_json = serde_json::json!({+ "title": "Project context",+ "slot_kind": "invariant",+ });+ let id2 = upsert_page(&mut conn, &p2).unwrap();++ assert_ne!(id1, id2, "frontmatter-only changes must supersede");+ let latest_frontmatter: String = conn+ .query_row(+ "SELECT frontmatter_json FROM pages WHERE id = ?1 AND is_latest = 1",+ params![id2.as_bytes()],+ |r| r.get(0),+ )+ .unwrap();+ assert!(+ latest_frontmatter.contains("invariant"),+ "latest row should store the updated slot_kind"+ );+ }+#[test]fn upsert_page_persists_and_resolves_links() {let (_tmp, mut conn, ws, proj) = fresh_db();diff --git a/crates/ai-memory-wiki/src/markdown.rs b/crates/ai-memory-wiki/src/markdown.rsindex 61068994..2d3b1905 100644--- a/crates/ai-memory-wiki/src/markdown.rs+++ b/crates/ai-memory-wiki/src/markdown.rs@@ -301,6 +301,21 @@ mod tests {assert_eq!(parsed.body, original.body);}+ #[test]+ fn round_trip_preserves_slot_kind_frontmatter() {+ let original = Markdown {+ frontmatter: serde_json::json!({+ "title": "Project context",+ "slot_kind": "invariant",+ }),+ body: "Stable project context.\n".into(),+ };+ let emitted = emit(&original).unwrap();+ let parsed = parse(&emitted).unwrap();+ assert_eq!(parsed.frontmatter["slot_kind"], "invariant");+ assert_eq!(parsed.body, original.body);+ }+#[test]fn emit_omits_empty_frontmatter() {let md = Markdown {diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 1a60e9fc..9513364d 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -176,7 +176,14 @@ backpressure, or single-writer SQLite actor.Pinned pages (`pinned: true` in frontmatter) are exempt from alldecay paths. Pages under `_slots/` are pinned automatically and surfaced-in briefing/explore snapshots as tiny editable memory slots.+in briefing/explore snapshots as tiny editable memory slots. Slot pages+may declare a write regime with `slot_kind: state` or+`slot_kind: invariant`; omitted means `state` for backwards+compatibility. Use `state` for mutable working context such as current+focus and pending items. Use `invariant` for high-resistance project+context, identity, rules, or user preferences; consolidation should not+rewrite an existing invariant slot unless new observations directly+contradict specific existing content.## Crate layoutdiff --git a/docs/prior-art-implementation-findings.md b/docs/prior-art-implementation-findings.mdindex cb7f8ced..caed7a3f 100644--- a/docs/prior-art-implementation-findings.md+++ b/docs/prior-art-implementation-findings.md@@ -129,7 +129,10 @@ Recommended shape:The important constraint is budget. Do not copy agentmemory's broadalways-injected context problem. Slots should be tiny, explicit, and-auditable.+auditable. When a slot's write regime matters, use frontmatter:+`slot_kind: invariant` for stable context/preferences and+`slot_kind: state` for mutable current focus or pending items. Missing+`slot_kind` defaults to `state`.### P0: Make Maintenance Scheduled, Not Only Manual