Skip to content

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

Rust

fix(lint): separate similarity candidates from contradictions

AkitaOnRailse1da2733dcde
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 85ed1d80..cc7f610d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,13 @@ version in [`docs/changelog/`](docs/changelog/):
## [Unreleased]
+### Changed
+
+- `memory_lint` now reports embedding-band pairs as
+ `similarity_candidate` instead of `contradiction`, and no longer infers that
+ a newer page supersedes an older one from timestamps alone. Explicit
+ `contradicts` edges remain `contradiction` findings (#1685).
+
### Added
- Added `[briefing] inject_on_subagent_start` to `.ai-memory.toml`. A project
diff --git a/crates/ai-memory-consolidate/src/lint.rs b/crates/ai-memory-consolidate/src/lint.rs
index af498cde..bdd83473 100644
--- a/crates/ai-memory-consolidate/src/lint.rs
+++ b/crates/ai-memory-consolidate/src/lint.rs
@@ -40,7 +40,8 @@ fn default_lint_severity() -> String {
/// One lint finding (rule-based or LLM-emitted).
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct LintFinding {
- /// Discriminator: `contradiction` | `stale` | `duplicate` | `empty` | `other`.
+ /// Discriminator: `contradiction` | `similarity_candidate` | `stale` |
+ /// `duplicate` | `empty` | `other`.
pub kind: String,
/// `info` | `warning`. Defaults to `"warning"` so older prompts that
/// omit the field don't hard-fail deserialization.
@@ -299,13 +300,13 @@ pub async fn run_lint(
});
}
- // Zero-LLM detected contradictions (A5): pages whose embeddings sit in the
+ // Zero-LLM similarity candidates (A5): pages whose embeddings sit in the
// (configurable, default 0.4–0.75) cosine-similarity band are "same topic,
- // not a near-duplicate" — the shape of a likely conflict. This DETECTS
- // contradictions beside the declared-`contradicts`-edge finding above,
- // using only stored vectors and cosine (invariant #13 — no provider
- // call). It emits advisory findings (invariant #16) and never persists an
- // edge.
+ // not a near-duplicate". Similarity alone does not prove disagreement, so
+ // this path emits `similarity_candidate`, distinct from the explicit
+ // `contradicts`-edge finding above. It uses only stored vectors and cosine
+ // (invariant #13 — no provider call), stays advisory (invariant #16), and
+ // never persists an edge.
//
// The band is a FIXED absolute cosine value, but background similarity is
// corpus-dependent: on a single-language or single-domain store, unrelated
@@ -520,22 +521,17 @@ fn in_contradiction_band(similarity: f32, low: f32, high: f32) -> bool {
(low..high).contains(&similarity)
}
-/// One page eligible for the band scan: its path, last-updated microseconds
-/// (for the newer-wins advisory), and its stored embedding.
+/// One page eligible for the band scan: its path and stored embedding.
struct BandCandidate {
path: String,
- updated_at_us: i64,
vector: Vec<f32>,
}
/// Pure pairwise band scan over a bounded, deterministically-ordered set of
-/// pages. Emits an advisory `contradiction` finding for each pair whose cosine
-/// similarity is in `[band_min, band_max)`, capped at `max_findings`.
-///
-/// Timestamp resolution is ADVISORY only: the message says the newer page
-/// supersedes on a timestamp basis, but the lint never deletes or edits
-/// anything (invariant #16). Pairs are visited in `(i, j)` order so the same
-/// input always yields the same capped subset.
+/// pages. Emits an advisory `similarity_candidate` finding for each pair whose
+/// cosine similarity is in `[band_min, band_max)`, capped at `max_findings`.
+/// Pairs are visited in `(i, j)` order so the same input always yields the same
+/// capped subset.
fn detected_contradiction_findings(
pages: &[BandCandidate],
band_min: f32,
@@ -550,24 +546,15 @@ fn detected_contradiction_findings(
continue;
}
let (a, b) = (&pages[i], &pages[j]);
- // Newer = larger updated_at_us. Ties resolve to `a` (the lexically
- // earlier path, since the caller sorts by path) for determinism.
- let (newer, older) = if a.updated_at_us >= b.updated_at_us {
- (a, b)
- } else {
- (b, a)
- };
- let newer_ts = Timestamp::from_microsecond(newer.updated_at_us)
- .map(|t| t.to_zoned(TimeZone::UTC).strftime("%Y-%m-%d").to_string())
- .unwrap_or_else(|_| "unknown".into());
findings.push(LintFinding {
- kind: "contradiction".into(),
+ kind: "similarity_candidate".into(),
severity: "info".into(),
message: format!(
"Pages {} and {} are similar (cosine {similarity:.2}) but not a \
- duplicate — likely conflicting. The newer page ({}, updated \
- {newer_ts}) supersedes {} on a timestamp basis; reconcile them.",
- a.path, b.path, newer.path, older.path,
+ near-duplicate. Similarity does not establish a contradiction \
+ or supersession; inspect the pair for compatible or conflicting \
+ claims.",
+ a.path, b.path,
),
pages: vec![a.path.clone(), b.path.clone()],
detail: None,
@@ -642,7 +629,6 @@ async fn detected_contradiction_pass(
if let Some(c) = by_id.get(&e.id) {
pages.push(BandCandidate {
path: c.path.as_str().to_string(),
- updated_at_us: c.updated_at_us,
vector: e.vector.clone(),
});
}
@@ -1323,22 +1309,21 @@ mod tests {
// Unit-length 2-D vectors: cosine similarity between them equals the dot
// product, so a chosen second component pins the similarity exactly.
- fn band(path: &str, updated_at_us: i64, vector: Vec<f32>) -> BandCandidate {
+ fn band(path: &str, vector: Vec<f32>) -> BandCandidate {
BandCandidate {
path: path.to_string(),
- updated_at_us,
vector,
}
}
- /// Two pages at cosine 0.6 ⇒ exactly one contradiction finding naming both,
- /// with newer-wins advice pointing at the more recently updated page.
+ /// Two pages at cosine 0.6 ⇒ exactly one similarity candidate naming both,
+ /// without claiming a contradiction or supersession.
#[test]
- fn band_scan_flags_a_mid_band_pair_newer_wins() {
+ fn band_scan_flags_a_mid_band_similarity_candidate() {
let pages = vec![
- band("concepts/old-claim.md", 1_000, vec![1.0, 0.0]),
+ band("concepts/old-claim.md", vec![1.0, 0.0]),
// dot([1,0],[0.6,0.8]) = 0.6 — squarely in the band.
- band("concepts/new-claim.md", 9_000, vec![0.6, 0.8]),
+ band("concepts/new-claim.md", vec![0.6, 0.8]),
];
let findings = detected_contradiction_findings(
&pages,
@@ -1352,15 +1337,15 @@ mod tests {
"one band pair ⇒ one finding: {findings:?}"
);
let f = &findings[0];
- assert_eq!(f.kind, "contradiction");
+ assert_eq!(f.kind, "similarity_candidate");
assert_eq!(f.severity, "info");
assert_eq!(f.pages.len(), 2);
assert!(f.pages.contains(&"concepts/old-claim.md".to_string()));
assert!(f.pages.contains(&"concepts/new-claim.md".to_string()));
- // Newer (larger updated_at_us) supersedes on a timestamp basis.
assert!(
- f.message.contains("concepts/new-claim.md") && f.message.contains("supersedes"),
- "newer page wins advisory: {}",
+ f.message.contains("does not establish a contradiction")
+ && f.message.contains("or supersession"),
+ "candidate must state the evidence limit: {}",
f.message
);
}
@@ -1370,9 +1355,9 @@ mod tests {
#[test]
fn band_scan_ignores_near_duplicates() {
let pages = vec![
- band("concepts/a.md", 1, vec![1.0, 0.0]),
+ band("concepts/a.md", vec![1.0, 0.0]),
// dot ≈ 0.98 — a near-duplicate, above the band.
- band("concepts/b.md", 2, vec![0.98, 0.199]),
+ band("concepts/b.md", vec![0.98, 0.199]),
];
let findings = detected_contradiction_findings(
&pages,
@@ -1395,8 +1380,8 @@ mod tests {
// dot([1,0],[0.7,x]) = 0.7 where x = sqrt(1 - 0.7^2).
let x = (1.0_f32 - 0.7 * 0.7).sqrt();
let pages = vec![
- band("concepts/a.md", 1, vec![1.0, 0.0]),
- band("concepts/b.md", 2, vec![0.7, x]),
+ band("concepts/a.md", vec![1.0, 0.0]),
+ band("concepts/b.md", vec![0.7, x]),
];
let default_findings = detected_contradiction_findings(
&pages,
@@ -1425,8 +1410,8 @@ mod tests {
#[test]
fn band_scan_ignores_unrelated_pairs() {
let pages = vec![
- band("concepts/a.md", 1, vec![1.0, 0.0]),
- band("concepts/b.md", 2, vec![0.2, 0.9798]),
+ band("concepts/a.md", vec![1.0, 0.0]),
+ band("concepts/b.md", vec![0.2, 0.9798]),
];
let findings = detected_contradiction_findings(
&pages,
@@ -1452,7 +1437,7 @@ mod tests {
)
.is_empty()
);
- let one = vec![band("concepts/a.md", 1, vec![1.0, 0.0])];
+ let one = vec![band("concepts/a.md", vec![1.0, 0.0])];
assert!(
detected_contradiction_findings(
&one,
@@ -1474,9 +1459,9 @@ mod tests {
let b = (55.0_f64).to_radians();
let c = (110.0_f64).to_radians();
let pages = vec![
- band("concepts/a.md", 1, vec![a.cos() as f32, a.sin() as f32]),
- band("concepts/b.md", 2, vec![b.cos() as f32, b.sin() as f32]),
- band("concepts/c.md", 3, vec![c.cos() as f32, c.sin() as f32]),
+ band("concepts/a.md", vec![a.cos() as f32, a.sin() as f32]),
+ band("concepts/b.md", vec![b.cos() as f32, b.sin() as f32]),
+ band("concepts/c.md", vec![c.cos() as f32, c.sin() as f32]),
];
assert_eq!(
detected_contradiction_findings(
diff --git a/crates/ai-memory-consolidate/tests/suite/aging_lifecycle.rs b/crates/ai-memory-consolidate/tests/suite/aging_lifecycle.rs
index 5780f797..755702ec 100644
--- a/crates/ai-memory-consolidate/tests/suite/aging_lifecycle.rs
+++ b/crates/ai-memory-consolidate/tests/suite/aging_lifecycle.rs
@@ -682,13 +682,13 @@ async fn s1_dedup_collapses_near_duplicate_cold_pages() {
);
}
-/// A5. Contradiction lint. Two cold semantic pages whose embeddings sit in the
-/// 0.4–0.75 cosine band produce ONE advisory `contradiction` finding naming
+/// A5. Similarity lint. Two cold semantic pages whose embeddings sit in the
+/// 0.4–0.75 cosine band produce ONE advisory `similarity_candidate` naming
/// both — and nothing is deleted or superseded (advisory only, invariant #16).
/// Embeddings are seeded as exact 2-D unit vectors so the similarity is pinned
/// squarely inside the band.
#[tokio::test]
-async fn s1_contradiction_lint_flags_band_pair_without_deleting() {
+async fn s1_similarity_lint_flags_band_pair_without_deleting() {
const PROVIDER: &str = "test-embedder";
const MODEL: &str = "unit-2d";
let fx = seed_fixture(false).await;
@@ -738,19 +738,20 @@ async fn s1_contradiction_lint_flags_band_pair_without_deleting() {
.await
.unwrap();
- let contradictions: Vec<_> = report
+ let candidates: Vec<_> = report
.findings
.iter()
- .filter(|f| f.kind == "contradiction")
+ .filter(|f| f.kind == "similarity_candidate")
.collect();
assert_eq!(
- contradictions.len(),
+ candidates.len(),
1,
"one band pair ⇒ one finding: {:?}",
report.findings
);
- let f = contradictions[0];
- assert_eq!(f.severity, "info", "contradiction findings are advisory");
+ let f = candidates[0];
+ assert_eq!(f.severity, "info", "similarity candidates are advisory");
+ assert!(!report.findings.iter().any(|f| f.kind == "contradiction"));
assert!(f.pages.contains(&"concepts/old-claim.md".to_string()));
assert!(f.pages.contains(&"concepts/new-claim.md".to_string()));
assert_eq!(
diff --git a/crates/ai-memory-consolidate/tests/suite/contradiction_lint.rs b/crates/ai-memory-consolidate/tests/suite/contradiction_lint.rs
index e600cc00..a400d4bd 100644
--- a/crates/ai-memory-consolidate/tests/suite/contradiction_lint.rs
+++ b/crates/ai-memory-consolidate/tests/suite/contradiction_lint.rs
@@ -2,9 +2,10 @@
//!
//! Invariants guarded (docs/design-memory-aging.md §A5):
//!
-//! 1. **Band pair ⇒ finding.** Two cold pages whose embeddings sit in the
-//! 0.4–0.75 cosine-similarity band produce one advisory `contradiction`
-//! finding naming both paths, with newer-wins advice.
+//! 1. **Band pair ⇒ candidate.** Two cold pages whose embeddings sit in the
+//! 0.4–0.75 cosine-similarity band produce one advisory
+//! `similarity_candidate` naming both paths without claiming conflict or
+//! supersession.
//! 2. **Near-duplicate ⇒ NOT a contradiction.** A pair at ≥0.75 is A3
//! dedup territory, never flagged here.
//! 3. **No embeddings ⇒ clean no-op** (never an error, never a provider call).
@@ -150,31 +151,16 @@ fn options_with_band(
}
}
-/// Two cold pages in the band ⇒ one advisory contradiction finding naming
-/// both, with newer-wins advice; nothing is deleted or rewritten.
+/// Two cold pages in the band ⇒ one advisory similarity candidate naming
+/// both without conflict or supersession claims; nothing is rewritten.
#[tokio::test]
-async fn band_pair_yields_advisory_contradiction() {
+async fn band_pair_yields_advisory_similarity_candidate() {
let fx = seed_fixture().await;
let old = write_semantic(&fx, "concepts/old-claim.md", "The retry budget is 3.").await;
let new = write_semantic(&fx, "concepts/new-claim.md", "The retry budget is 5.").await;
// dot([1,0],[0.6,0.8]) = 0.6 — squarely in the 0.4–0.75 band.
seed_embedding(&fx, old, &[1.0, 0.0]);
seed_embedding(&fx, new, &[0.6, 0.8]);
- // Make `new` the more recently updated page so it wins the timestamp advice.
- {
- let conn = rusqlite::Connection::open(fx.tmp.path().join("db/memory.sqlite")).unwrap();
- conn.execute(
- "UPDATE pages SET updated_at = updated_at + 1000000 \
- WHERE workspace_id = ?1 AND project_id = ?2 AND path = ?3 AND is_latest = 1",
- params![
- fx.ws.as_bytes(),
- fx.proj.as_bytes(),
- "concepts/new-claim.md"
- ],
- )
- .unwrap();
- }
-
let before = latest_page_count(&fx);
let report = run_lint(
&fx.store.reader,
@@ -187,26 +173,28 @@ async fn band_pair_yields_advisory_contradiction() {
.await
.unwrap();
- let contradictions: Vec<_> = report
+ let candidates: Vec<_> = report
.findings
.iter()
- .filter(|f| f.kind == "contradiction")
+ .filter(|f| f.kind == "similarity_candidate")
.collect();
assert_eq!(
- contradictions.len(),
+ candidates.len(),
1,
- "one band pair ⇒ one contradiction finding: {:?}",
+ "one band pair ⇒ one similarity candidate: {:?}",
report.findings
);
- let f = contradictions[0];
- assert_eq!(f.severity, "info", "detected contradictions are advisory");
+ let f = candidates[0];
+ assert_eq!(f.severity, "info", "similarity candidates are advisory");
assert!(f.pages.contains(&"concepts/old-claim.md".to_string()));
assert!(f.pages.contains(&"concepts/new-claim.md".to_string()));
assert!(
- f.message.contains("concepts/new-claim.md") && f.message.contains("supersedes"),
- "newer page wins on a timestamp basis: {}",
+ f.message.contains("does not establish a contradiction")
+ && f.message.contains("or supersession"),
+ "candidate must state the evidence limit: {}",
f.message
);
+ assert!(!report.findings.iter().any(|f| f.kind == "contradiction"));
// Advisory (#16): nothing deleted or superseded.
assert_eq!(
@@ -243,7 +231,10 @@ async fn raised_floor_suppresses_the_band_pair_end_to_end() {
.unwrap();
assert!(
- !report.findings.iter().any(|f| f.kind == "contradiction"),
+ !report
+ .findings
+ .iter()
+ .any(|f| f.kind == "similarity_candidate"),
"a 0.7 floor must drop the 0.6-similarity pair the default 0.4 floor admits: {:?}",
report.findings
);
@@ -272,7 +263,10 @@ async fn near_duplicate_is_not_a_contradiction() {
.unwrap();
assert!(
- !report.findings.iter().any(|f| f.kind == "contradiction"),
+ !report
+ .findings
+ .iter()
+ .any(|f| f.kind == "similarity_candidate"),
"a near-duplicate must not be flagged as a contradiction: {:?}",
report.findings
);
@@ -302,7 +296,7 @@ async fn no_embeddings_is_a_clean_no_op() {
!with_coord
.findings
.iter()
- .any(|f| f.kind == "contradiction"),
+ .any(|f| f.kind == "similarity_candidate"),
"no embeddings ⇒ no contradiction findings: {:?}",
with_coord.findings
);
@@ -322,7 +316,7 @@ async fn no_embeddings_is_a_clean_no_op() {
!without_coord
.findings
.iter()
- .any(|f| f.kind == "contradiction"),
+ .any(|f| f.kind == "similarity_candidate"),
"embedding: None ⇒ no contradiction findings: {:?}",
without_coord.findings
);
@@ -365,7 +359,10 @@ async fn contradiction_pass_skips_expired_pages() {
.unwrap();
assert!(
- !report.findings.iter().any(|f| f.kind == "contradiction"),
+ !report
+ .findings
+ .iter()
+ .any(|f| f.kind == "similarity_candidate"),
"expired pages must not produce contradiction findings: {:?}",
report.findings
);
@@ -459,10 +456,11 @@ async fn llm_lint_pass_does_not_audit_the_previous_lint_report() {
/// A positive pair contains incompatible simultaneous values for the same
/// setting and scope. Compatible active pairs are negatives. Expired,
/// superseded and foreign-project pairs exercise eligibility and are excluded
-/// from the classification metrics. A prediction means any `kind = contradiction`
-/// finding, including an advisory similarity candidate; it does not mean the
-/// server independently verified the conflict. The typed-edge control also
-/// contains conflicting prose, so its label does not rely on the edge alone.
+/// from the classification metrics. A contradiction prediction is only a
+/// `kind = contradiction` finding. A `similarity_candidate` is tracked
+/// separately because it is not independent evidence of conflict. The
+/// typed-edge control also contains conflicting prose, so its label does not
+/// rely on the edge alone.
#[derive(serde::Deserialize)]
#[serde(deny_unknown_fields)]
struct EvidenceCase {
@@ -553,7 +551,7 @@ async fn seed_evidence_case(case: &EvidenceCase) -> Fixture {
fx
}
-async fn evidence_findings(fx: &Fixture) -> Vec<(String, Vec<String>)> {
+async fn evidence_findings(fx: &Fixture) -> Vec<(String, String, Vec<String>)> {
let report = run_lint(
&fx.store.reader,
&fx.wiki,
@@ -567,8 +565,8 @@ async fn evidence_findings(fx: &Fixture) -> Vec<(String, Vec<String>)> {
report
.findings
.into_iter()
- .filter(|finding| finding.kind == "contradiction")
- .map(|finding| (finding.severity, finding.pages))
+ .filter(|finding| finding.kind == "contradiction" || finding.kind == "similarity_candidate")
+ .map(|finding| (finding.kind, finding.severity, finding.pages))
.collect()
}
@@ -580,12 +578,21 @@ struct EvidenceCounts {
fn_: usize,
excluded: usize,
findings: usize,
+ similarity_candidates: usize,
}
impl EvidenceCounts {
- fn record(&mut self, case: &EvidenceCase, findings: usize) {
- self.findings += findings;
- match (case.label, findings > 0) {
+ fn record(&mut self, case: &EvidenceCase, findings: &[(String, String, Vec<String>)]) {
+ self.findings += findings.len();
+ let contradictions = findings
+ .iter()
+ .filter(|(kind, _, _)| kind == "contradiction")
+ .count();
+ self.similarity_candidates += findings
+ .iter()
+ .filter(|(kind, _, _)| kind == "similarity_candidate")
+ .count();
+ match (case.label, contradictions > 0) {
(EvidenceLabel::Conflict, true) => self.tp += 1,
(EvidenceLabel::Conflict, false) => self.fn_ += 1,
(EvidenceLabel::Compatible, true) => self.fp += 1,
@@ -629,7 +636,16 @@ async fn labeled_evidence_pairs_record_current_classification() {
assert!(first.is_empty(), "excluded pair: {}", case.id);
}
if matches!(case.setup, EvidenceSetup::Declared) {
- assert_eq!(first[0].0, "warning", "typed edge control");
+ assert_eq!(first[0].0, "contradiction", "typed edge control kind");
+ assert_eq!(first[0].1, "warning", "typed edge control severity");
+ } else if matches!(case.setup, EvidenceSetup::Active) && !first.is_empty() {
+ assert!(
+ first
+ .iter()
+ .all(|(kind, _, _)| kind == "similarity_candidate"),
+ "similarity-only findings must remain candidates: {}",
+ case.id
+ );
}
assert_eq!(
first,
@@ -643,7 +659,7 @@ async fn labeled_evidence_pairs_record_current_classification() {
"lint mutated pages: {}",
case.id
);
- counts.record(case, first.len());
+ counts.record(case, &first);
}
assert_eq!(cases.len(), 11);
counts.report();
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 00ccbf4b..618c5302 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -772,7 +772,7 @@ long-lived entry there is expected policy behavior, not a fault.
| `memory_delete_page` | destructive | Delete a single page by exact `path`; `scope: "profile"` deletes from the caller's cross-project profile. Fires the admission chain (op=delete); idempotent. Optional `expected_page_id` deletes only if that is still the latest version; otherwise nothing is deleted and the call returns `reason: "precondition_failed"`. |
| `memory_restore_page` | destructive | Admin only, like `/admin/restore-page`. Without `rev`, list the git checkpoints that changed `path`. With `rev`, write that version (body and frontmatter metadata) back through the `memory_write_page` path (sanitizer, admission, slots, supersession), including a deleted page. Project pages only, not `scope: "profile"`. |
| `memory_forget_sweep` | destructive | Retention pass: evict cold pages through the wiki layer, purge aged tombstone ancestry, and hard-delete TTL-expired pages. `dry_run=true` for preview. |
-| `memory_lint` | destructive | Rule-based + LLM contradiction findings → `wiki/_lint/`. Also runs a **zero-LLM contradiction detector** (design-memory-aging.md A5): cold semantic/procedural pages whose already-stored embeddings sit in the `contradiction_band_min`–`contradiction_band_max` cosine-similarity band (default 0.4–0.75; "same topic, not a near-duplicate"; at/above the max is A3 dedup, below the min unrelated) get an advisory `contradiction` finding with newer-wins timestamp advice. Bounded (one embeddings load over the capped cold set, capped findings, deterministic); a clean no-op with no embedder configured; advisory-only (never deletes/edits/supersedes a page and persists no edge, invariants #13, #16, #2), so no migration. On a single-language or single-domain store, background similarity between unrelated pages already sits well above the default floor, so the band measures domain proximity more than conflict and produces noisy findings, so raise `contradiction_band_min` (`config.toml` or `AI_MEMORY_CONTRADICTION_BAND_MIN`) for such a store. |
+| `memory_lint` | destructive | Rule-based + LLM contradiction findings → `wiki/_lint/`. Also runs a **zero-LLM similarity candidate detector** (design-memory-aging.md A5): cold semantic/procedural pages whose already-stored embeddings sit in the `contradiction_band_min`–`contradiction_band_max` cosine-similarity band (default 0.4–0.75; "same topic, not a near-duplicate"; at/above the max is A3 dedup, below the min unrelated) get an advisory `similarity_candidate` finding. Similarity alone never claims contradiction or supersession; explicit `contradicts` edges still emit `contradiction`. The scan is bounded (one embeddings load over the capped cold set, capped findings, deterministic), a clean no-op with no embedder configured, and advisory-only (never deletes/edits/supersedes a page and persists no edge, invariants #13, #16, #2), so it needs no migration. On a single-language or single-domain store, background similarity between unrelated pages can sit above the default floor; raise `contradiction_band_min` (`config.toml` or `AI_MEMORY_CONTRADICTION_BAND_MIN`) to trim that review queue. |
| `memory_install_self_routing` | read-only | Return the canonical slim routing snippet plus managed Agent Skill payloads and target hints for CLAUDE.md / AGENTS.md installs. |
`memory_briefing`, `memory_explore`, `memory_write_page`,
diff --git a/docs/cookbook.md b/docs/cookbook.md
index 600a8168..2b05d6d9 100644
--- a/docs/cookbook.md
+++ b/docs/cookbook.md
@@ -276,11 +276,12 @@ compacted or merged stays in git and the supersession chain, recoverable with
- **Keep used memory longer:** nothing to configure. A page you open, search,
or reach through a related-pages walk is reinforced automatically and resists
decay.
-- **Surface likely contradictions:** run `memory_lint` (through your agent or the
- CLI); with embeddings configured it flags pairs of same-topic pages that look
- like they conflict, advisory only. Similarity reads shared vocabulary as much
- as disagreement, so a single-domain or single-language store yields mostly
- candidate pairs: read each finding as a pair to check, not as a defect. If
+- **Review similar knowledge:** run `memory_lint` (through your agent or the
+ CLI); with embeddings configured it emits `similarity_candidate` findings
+ for same-topic page pairs, advisory only. Similarity reads shared vocabulary
+ as much as disagreement, so read each candidate as a pair to check, not as a
+ contradiction or a supersession instruction. Explicit `contradicts` edges
+ remain `contradiction` findings. If
that noise is too high, raise `contradiction_band_min` (`config.toml` or
`AI_MEMORY_CONTRADICTION_BAND_MIN`, default `0.4`). On such a store the
band measures domain proximity more than conflict, so a higher floor trims
diff --git a/docs/design-memory-aging.md b/docs/design-memory-aging.md
index 90b22c45..05ee3932 100644
--- a/docs/design-memory-aging.md
+++ b/docs/design-memory-aging.md
@@ -237,16 +237,17 @@ Everything in A works with no provider and does not require ranking changes.
- *Failure modes:* filters a terse-but-important note → tune threshold low; keep it
advisory (skip-from-consolidation, not delete).
-**A5. Zero-LLM `contradicts` edges via similarity band.**
-- *What:* detect likely contradictions between pages in the 0.4–0.75 cosine band
- (mcp-memory-service's heuristic) and record a `contradicts` edge resolved by
- timestamp (newer wins), feeding the existing `memory_lint`.
-- *Why:* surfaces stale/conflicting knowledge without a provider; lint already
- exists to consume it.
-- *Mechanism:* pairwise within cold clusters (bounded); emit an edge + a lint
- finding. Timestamp resolution only *flags*, never auto-deletes.
-- *Schema delta:* reuse `page_evidence`/edge tables; add a `contradicts` edge kind
- if not present (V66 if needed).
+**A5. Zero-LLM similarity candidates.**
+- *What:* surface cold page pairs in the 0.4–0.75 cosine band
+ (mcp-memory-service's heuristic) as `similarity_candidate` lint findings.
+ Similarity alone does not establish contradiction or supersession.
+- *Why:* gives an operator a bounded review queue without overstating what the
+ embedding evidence proves. Explicit `contradicts` edges remain separate
+ `contradiction` findings.
+- *Mechanism:* pairwise within cold clusters (bounded); emit an advisory lint
+ finding only. Never infer an ordering from timestamps.
+- *Schema delta:* none; the candidate is computed at lint time and no edge is
+ persisted.
- *Invariants:* #13; lint stays advisory (#16: a contradiction is not a delete).
- *R2 bar:* none for detection; if the edge later feeds *rank* (per
`design-hindsight-borrowings.md` §4) that step is R2-gated separately.
@@ -262,14 +263,14 @@ current classification, including compatible pairs inside the band and a
conflicting pair above it; they do not estimate production precision or propose
a new response contract.
-A prediction is any `contradiction` finding, including an advisory similarity
-candidate. Positives contain incompatible simultaneous values for the same
-setting and scope; compatible active pairs are negatives. Superseded, expired
-and foreign-project pairs test eligibility separately and do not enter the
-classification metrics. The declared-edge control contains conflicting
-prose and has no embeddings. Expected counts document the current behavior;
-labels should remain independent when an approved classifier change updates
-those counts.
+A contradiction prediction is only a `contradiction` finding;
+`similarity_candidate` findings are counted separately. Positives contain
+incompatible simultaneous values for the same setting and scope; compatible
+active pairs are negatives. Superseded, expired and foreign-project pairs test
+eligibility separately and do not enter the classification metrics. The
+declared-edge control contains conflicting prose and has no embeddings.
+Expected counts document the current behavior; labels remain independent of
+the classifier output.
```bash
cargo test -p ai-memory-consolidate labeled_evidence_pairs_record_current_classification -- --nocapture
@@ -281,7 +282,7 @@ false-positive/false-negative rates and checks repeated classification parity.
The optional second command reports lint p50/p95 over 20 runs per isolated pair after a
warm-up, excluding fixture creation. Both run offline without an LLM. Timing has
no pass threshold and is not a benchmark of a full store. Neither changes lint's
-public classification; that decision remains in the RFC.
+classification while it runs.
### Bucket B — LLM "dream" pass (opt-in, OFF by default, R2-gated)