Skip to content

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.md
index 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
### Added
diff --git a/crates/ai-memory-consolidate/src/consolidator.rs b/crates/ai-memory-consolidate/src/consolidator.rs
index 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.rs
index 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.rs
index 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.rs
index 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]) -> StoreResu
Ok(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.rs
index 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.md
index 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 all
decay 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 layout
diff --git a/docs/prior-art-implementation-findings.md b/docs/prior-art-implementation-findings.md
index 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 broad
always-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