Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

feat(audit): report projects split by case or accents

AkitaOnRailsc02e3c0d384d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 43b8f09b..ea2d59b3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,14 @@ version in [`docs/changelog/`](docs/changelog/):
### Added
+- `ai-memory audit-contamination` reports projects whose names differ only by
+ spelling: two rows whose names are equal after case folding, Unicode
+ composition and separators (`renato` / `Renato` / `Rénato`). That is the
+ signature of one working copy reaching the server twice, which no
+ cwd-anchored check can see; each finding names the peer projects and their
+ page and session counts, and suggests a marker or a merge. Read-only, and it
+ never fires for a project that merely shares a prefix (#1645).
+
- Added an optional `[query_answer] max_context_tokens` admission budget for
answer synthesis. It preserves retrieval hits, reports omitted or clipped
evidence, prioritizes known newer corrections, prefers whole snippets and
diff --git a/Cargo.lock b/Cargo.lock
index 1607a1ed..71de19a9 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -262,6 +262,7 @@ dependencies = [
"base64 0.22.1",
"fs2",
"getrandom 0.3.4",
+ "icu_normalizer",
"jiff",
"parking_lot",
"refinery",
diff --git a/crates/ai-memory-cli/src/commands/audit_contamination.rs b/crates/ai-memory-cli/src/commands/audit_contamination.rs
index 07bacb06..a4ca5e6c 100644
--- a/crates/ai-memory-cli/src/commands/audit_contamination.rs
+++ b/crates/ai-memory-cli/src/commands/audit_contamination.rs
@@ -24,6 +24,8 @@ struct Report {
struct Summary {
#[serde(default)]
sessions_misbucketed: usize,
+ #[serde(default)]
+ project_name_collisions: usize,
}
#[derive(Debug, Deserialize, Serialize)]
@@ -38,6 +40,12 @@ struct Finding {
expected_project: Option<String>,
#[serde(default)]
cwd: Option<String>,
+ #[serde(default)]
+ peer_projects: Option<String>,
+ #[serde(default)]
+ pages: Option<u64>,
+ #[serde(default)]
+ sessions: Option<u64>,
}
/// Run the `audit-contamination` subcommand.
@@ -56,12 +64,15 @@ pub async fn run(config: &Config, args: AuditContaminationArgs) -> Result<()> {
}
if report.findings.is_empty() {
- println!("No structural contamination found (no session mis-bucketed by cwd).");
+ println!(
+ "No structural contamination found (no session mis-bucketed by cwd, no project \
+ name collisions)."
+ );
return Ok(());
}
println!(
- "Contamination audit: {} session(s) mis-bucketed.",
- report.summary.sessions_misbucketed
+ "Contamination audit: {} session(s) mis-bucketed, {} project(s) with a colliding name.",
+ report.summary.sessions_misbucketed, report.summary.project_name_collisions
);
for f in &report.findings {
let expected = f.expected_project.as_deref().unwrap_or("?");
@@ -75,6 +86,18 @@ pub async fn run(config: &Config, args: AuditContaminationArgs) -> Result<()> {
f.cwd.as_deref().unwrap_or("?"),
expected,
),
+ "project_name_collision" => println!(
+ " [{}] project {} ({}/{}): {} page(s), {} session(s); collides with {}. \
+ Add a `.ai-memory.toml` marker, or merge the two once `merge-project` exists \
+ (#1645).",
+ f.confidence,
+ f.entity_id,
+ f.landed_workspace,
+ f.landed_project,
+ f.pages.unwrap_or(0),
+ f.sessions.unwrap_or(0),
+ f.peer_projects.as_deref().unwrap_or("?"),
+ ),
other => println!(
" [{}] {} {} in {}/{}",
f.confidence, other, f.entity_id, f.landed_workspace, f.landed_project
diff --git a/crates/ai-memory-store/Cargo.toml b/crates/ai-memory-store/Cargo.toml
index d7fc87cc..4e0e53ad 100644
--- a/crates/ai-memory-store/Cargo.toml
+++ b/crates/ai-memory-store/Cargo.toml
@@ -19,6 +19,7 @@ serde.workspace = true
serde_json.workspace = true
tokio.workspace = true
tracing.workspace = true
+icu_normalizer.workspace = true
jiff.workspace = true
uuid.workspace = true
sha2.workspace = true
diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rs
index 820cb0a5..efaf0e0c 100644
--- a/crates/ai-memory-store/src/lib.rs
+++ b/crates/ai-memory-store/src/lib.rs
@@ -103,6 +103,7 @@ pub use reader::{
SessionPromptTitles, SessionSummary, SessionToolTitles, SettledPage, StatusCounts,
StorageStatus, StoredEmbedding, StoredPageBody, StreamTimings, VectorQuery, WorkspaceScopeRow,
WorkspaceSummary, f32_vec_to_bytes, highlighted_snippet_html, plain_snippet,
+ project_name_fold_key,
};
pub use retrieval_tuning::{RetrievalTuning, is_session_recall_query};
pub use scope::{
diff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rs
index b14faf6c..5a489c72 100644
--- a/crates/ai-memory-store/src/reader.rs
+++ b/crates/ai-memory-store/src/reader.rs
@@ -6,6 +6,7 @@
//! soft cap: a connection that comes back when the pool is already full
//! is simply dropped.
+use std::collections::BTreeMap;
use std::fmt::Write as _;
use std::path::{Path, PathBuf};
use std::sync::Arc;
@@ -1784,6 +1785,27 @@ pub struct StatusCounts {
pub evidence_rows: u64,
}
+/// The key two project names share when only their spelling differs
+/// (#1645).
+///
+/// Case folds and decomposes first, so `Renato` and `Renato` written with a
+/// combining accent are one key; then it keeps letters, digits, whitespace and
+/// the separators a project name can legitimately use, which drops the
+/// combining marks themselves and stray punctuation. It is a *finding*
+/// heuristic, deliberately a little broad: a false positive costs a line in a
+/// read-only report, while a split project costs a quarter of someone's memory.
+#[must_use]
+pub fn project_name_fold_key(name: &str) -> String {
+ let decomposed = icu_normalizer::DecomposingNormalizer::new_nfd().normalize(name);
+ decomposed
+ .chars()
+ .filter(|c| c.is_alphanumeric() || c.is_whitespace() || matches!(c, '-' | '_' | '.'))
+ .collect::<String>()
+ .to_lowercase()
+ .trim()
+ .to_string()
+}
+
/// One likely cross-project contamination finding from
/// [`ReaderPool::audit_contamination`]. Advisory only — it flags STRUCTURAL
/// mislandings (an entity whose identity disagrees with the bucket it landed
@@ -1810,6 +1832,17 @@ pub struct ContaminationFinding {
/// Originating session cwd — the prefix-resolution evidence (CHECK A).
#[serde(skip_serializing_if = "Option::is_none")]
pub cwd: Option<String>,
+ /// The other project(s) this name collides with, comma-separated
+ /// (CHECK B). Names only: the fix is a marker or `merge-project`, and the
+ /// reader needs both spellings.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub peer_projects: Option<String>,
+ /// Page count of this project (CHECK B).
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub pages: Option<u64>,
+ /// Session count of this project (CHECK B).
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub sessions: Option<u64>,
}
/// Per-check counts for an [`ReaderPool::audit_contamination`] run.
@@ -1817,6 +1850,9 @@ pub struct ContaminationFinding {
pub struct ContaminationSummary {
/// Sessions whose cwd prefix-resolves to a different project (CHECK A).
pub sessions_misbucketed: usize,
+ /// Projects whose names collide with another project's in one workspace
+ /// (CHECK B).
+ pub project_name_collisions: usize,
}
/// Result of [`ReaderPool::audit_contamination`] — advisory, never mutates.
@@ -12441,10 +12477,13 @@ impl ReaderPool {
// boundary and safety rules as the runtime resolver.
type Candidate = (String, WorkspaceId, ProjectId, String, String, String);
type Prefix = (WorkspaceId, ProjectId, String, String);
- let (mut findings, candidates, prefixes): (
+ // CHECK B's input: every project in scope with its counts.
+ type ProjectRow = (String, String, Vec<u8>, String, u64, u64);
+ let (mut findings, candidates, prefixes, projects): (
Vec<ContaminationFinding>,
Vec<Candidate>,
Vec<Prefix>,
+ Vec<ProjectRow>,
) = self
.with_conn(move |conn| {
// CHECK A findings are built after this closure (they need the
@@ -12562,7 +12601,38 @@ impl ReaderPool {
}
}
- Ok((findings, candidates, prefixes))
+ // CHECK B: project rows with their page and session counts.
+ // The fold happens outside the connection; the counts ride the
+ // same query so a large store costs two index scans, not 2N.
+ let mut p_sql = String::from(
+ "SELECT lower(hex(p.id)), wl.name, p.id, p.name, \
+ (SELECT COUNT(*) FROM pages pg WHERE pg.project_id = p.id \
+ AND pg.is_latest = 1), \
+ (SELECT COUNT(*) FROM sessions s WHERE s.project_id = p.id) \
+ FROM projects p JOIN workspaces wl ON wl.id = p.workspace_id",
+ );
+ if scoped {
+ p_sql.push_str(" WHERE p.workspace_id = ? AND p.id = ?");
+ }
+ let mut projects: Vec<ProjectRow> = Vec::new();
+ {
+ let mut stmt = conn.prepare(&p_sql)?;
+ let rows = stmt.query_map(params_from_iter(scope_params.iter()), |row| {
+ Ok((
+ row.get::<_, String>(0)?,
+ row.get::<_, String>(1)?,
+ row.get::<_, Vec<u8>>(2)?,
+ row.get::<_, String>(3)?,
+ u64::try_from(row.get::<_, i64>(4)?).unwrap_or(0),
+ u64::try_from(row.get::<_, i64>(5)?).unwrap_or(0),
+ ))
+ })?;
+ for r in rows {
+ projects.push(r?);
+ }
+ }
+
+ Ok((findings, candidates, prefixes, projects))
})
.await?;
@@ -12588,6 +12658,43 @@ impl ReaderPool {
landed_project: landed_proj_name,
expected_project: Some(resolved_name.clone()),
cwd: Some(cwd),
+ peer_projects: None,
+ pages: None,
+ sessions: None,
+ });
+ }
+ }
+
+ // CHECK B: projects whose names collide once spelling differences
+ // cannot be told apart (case, Unicode composition, separators). Two
+ // rows mean one working copy reached two projects, and no read can say
+ // which one a marker-less directory means (#1645).
+ let mut groups: BTreeMap<String, Vec<&ProjectRow>> = BTreeMap::new();
+ for project in &projects {
+ groups
+ .entry(project_name_fold_key(&project.3))
+ .or_default()
+ .push(project);
+ }
+ for (_, peers) in groups.iter().filter(|(_, peers)| peers.len() > 1) {
+ for project in peers {
+ let others: Vec<&str> = peers
+ .iter()
+ .filter(|peer| peer.0 != project.0)
+ .map(|peer| peer.3.as_str())
+ .collect();
+ findings.push(ContaminationFinding {
+ check: "project_name_collision",
+ confidence: "medium",
+ entity_kind: "project",
+ entity_id: project.0.clone(),
+ landed_workspace: project.1.clone(),
+ landed_project: project.3.clone(),
+ expected_project: None,
+ cwd: None,
+ peer_projects: Some(others.join(", ")),
+ pages: Some(project.4),
+ sessions: Some(project.5),
});
}
}
@@ -12597,6 +12704,10 @@ impl ReaderPool {
.iter()
.filter(|f| f.check == "session_wrong_bucket")
.count(),
+ project_name_collisions: findings
+ .iter()
+ .filter(|f| f.check == "project_name_collision")
+ .count(),
};
Ok(ContaminationReport { summary, findings })
}
diff --git a/crates/ai-memory-store/tests/suite/audit_contamination.rs b/crates/ai-memory-store/tests/suite/audit_contamination.rs
index 55c2e56e..c9fac437 100644
--- a/crates/ai-memory-store/tests/suite/audit_contamination.rs
+++ b/crates/ai-memory-store/tests/suite/audit_contamination.rs
@@ -282,3 +282,132 @@ async fn audit_scope_restricts_to_landed_bucket() {
"a scoped audit returns only findings landed in the scoped project"
);
}
+
+/// CHECK B: one working copy that reached the server under two spellings
+/// (#1645). `renato` and `Renato` are one directory on a case-insensitive
+/// filesystem; `Rénato` is the same name typed with an accent. Neither has a
+/// cwd anomaly, so only the name check can see them — and a project that
+/// merely shares a prefix (`renato-2`) is the control.
+#[tokio::test]
+async fn audit_flags_projects_split_by_case_or_accents() {
+ let tmp = tempfile::tempdir().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let conn = Connection::open(store.db_path()).unwrap();
+ let now = 1_700_000_000_000_i64;
+ let ws = id(1);
+ conn.execute(
+ "INSERT INTO workspaces (id, name, created_at) VALUES (?1, 'w', ?2)",
+ params![&ws[..], now],
+ )
+ .unwrap();
+ for (n, name) in [
+ (2u8, "renato"),
+ (3, "Renato"),
+ (4, "R\u{e9}nato"), // Rénato, composed
+ (5, "renato-2"),
+ (6, "widget"),
+ ] {
+ conn.execute(
+ "INSERT INTO projects (id, workspace_id, name, created_at) \
+ VALUES (?1, ?2, ?3, ?4)",
+ params![&id(n)[..], &ws[..], name, now],
+ )
+ .unwrap();
+ }
+ drop(conn);
+
+ let report = store.reader.audit_contamination(None, None).await.unwrap();
+ let collisions: Vec<&str> = report
+ .findings
+ .iter()
+ .filter(|f| f.check == "project_name_collision")
+ .map(|f| f.landed_project.as_str())
+ .collect();
+
+ assert!(
+ collisions.contains(&"renato") && collisions.contains(&"Renato"),
+ "case-only split is reported: {collisions:?}"
+ );
+ assert!(
+ collisions.contains(&"R\u{e9}nato"),
+ "accent-only split is reported: {collisions:?}"
+ );
+ assert!(
+ !collisions.contains(&"renato-2") && !collisions.contains(&"widget"),
+ "a different name is not a collision: {collisions:?}"
+ );
+ assert_eq!(
+ report.summary.project_name_collisions, 3,
+ "three spellings of one name"
+ );
+
+ let one = report
+ .findings
+ .iter()
+ .find(|f| f.landed_project == "renato")
+ .unwrap();
+ assert_eq!(one.entity_kind, "project");
+ assert_eq!(one.confidence, "medium");
+ let peers = one.peer_projects.as_deref().unwrap_or_default();
+ assert!(
+ peers.contains("Renato") && peers.contains("R\u{e9}nato"),
+ "each finding names its peers: {peers}"
+ );
+ assert_eq!(one.pages, Some(0));
+ assert_eq!(one.sessions, Some(0));
+}
+
+/// The fold itself: what counts as the same name, and what does not.
+#[test]
+fn project_name_fold_key_matches_spelling_not_meaning() {
+ let key = ai_memory_store::project_name_fold_key;
+ assert_eq!(key("renato"), key("Renato"));
+ assert_eq!(key("R\u{e9}nato"), key("Renato"));
+ assert_eq!(key("felipe-nr-judoka"), key("Felipe-NR-Judoka"));
+ assert_ne!(key("renato"), key("renato2"));
+ assert_ne!(key("widget"), key("gadget"));
+ assert_eq!(key(" api "), "api");
+}
+
+/// A scoped audit still reports collisions inside the requested project, and
+/// nothing outside it.
+#[tokio::test]
+async fn scoped_audit_limits_collisions_to_the_requested_project() {
+ let tmp = tempfile::tempdir().unwrap();
+ let store = Store::open(tmp.path()).unwrap();
+ let conn = Connection::open(store.db_path()).unwrap();
+ let now = 1_700_000_000_000_i64;
+ let (ws, a, b) = (id(1), id(2), id(3));
+ conn.execute(
+ "INSERT INTO workspaces (id, name, created_at) VALUES (?1, 'w', ?2)",
+ params![&ws[..], now],
+ )
+ .unwrap();
+ for (pid, name) in [(&a, "api"), (&b, "API")] {
+ conn.execute(
+ "INSERT INTO projects (id, workspace_id, name, created_at) VALUES (?1, ?2, ?3, ?4)",
+ params![&pid[..], &ws[..], name, now],
+ )
+ .unwrap();
+ }
+ drop(conn);
+
+ let all = store.reader.audit_contamination(None, None).await.unwrap();
+ assert_eq!(all.summary.project_name_collisions, 2);
+
+ let scoped = store
+ .reader
+ .audit_contamination(
+ Some((
+ WorkspaceId::from_slice(&ws).unwrap(),
+ ProjectId::from_slice(&a).unwrap(),
+ )),
+ None,
+ )
+ .await
+ .unwrap();
+ assert_eq!(
+ scoped.summary.project_name_collisions, 0,
+ "a single scoped project cannot collide with itself in the same workspace filter"
+ );
+}