Skip to content

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

Rust

feat(lint): make the A5 contradiction-similarity band configurable

AkitaOnRails115895cbe1c7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2cb16039..b9c36002 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Added
+- `contradiction_band_min` / `contradiction_band_max` config keys (env:
+ `AI_MEMORY_CONTRADICTION_BAND_MIN` / `AI_MEMORY_CONTRADICTION_BAND_MAX`)
+ make `memory_lint`'s A5 zero-LLM contradiction-detection cosine-similarity
+ band configurable, defaulting to the historical fixed `0.4`–`0.75`. The
+ band is a fixed absolute cosine value, but background similarity is
+ corpus-dependent: on a single-language or single-domain store, unrelated
+ pages already sit above the general-purpose floor, so the default band
+ measures domain proximity more than conflict and produces noisy findings.
+ Raising `contradiction_band_min` trims that noise. Rejected at config load
+ unless `0.0 <= contradiction_band_min < contradiction_band_max <= 1.0` and
+ both are finite. (#853)
- Fedora users can install prebuilt x86_64 and aarch64 RPMs from GitHub
Releases, with the existing native systemd service assets. (#858)
- `embedding_query_prefix` / `embedding_document_prefix` config keys (env:
diff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rs
index 2759e94a..46c4184b 100644
--- a/crates/ai-memory-cli/src/commands/serve.rs
+++ b/crates/ai-memory-cli/src/commands/serve.rs
@@ -1084,6 +1084,7 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {
.with_decay_breadth_weight(config.decay.breadth_weight)
.with_observation_retention(config.decay.observation_retention())
.with_compact_cold_episodic(config.decay.compact_cold_episodic)
+ .with_contradiction_band(config.contradiction_band_min, config.contradiction_band_max)
.with_auto_improve_require_approval(config.auto_improve.require_approval)
.with_auto_improve_review_config(auto_improve_review_config_from_settings(
&config.auto_improve,
@@ -1117,6 +1118,8 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {
config.decay,
config.dream,
activity_clock,
+ config.contradiction_band_min,
+ config.contradiction_band_max,
)
.await;
@@ -1309,6 +1312,8 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {
embedder: embedder.clone(),
provider_health: provider_health.clone(),
decay_params,
+ contradiction_band_min: config.contradiction_band_min,
+ contradiction_band_max: config.contradiction_band_max,
data_dir: config.data_dir.clone(),
db_path: store.db_path().to_path_buf(),
bind: bind.clone(),
@@ -1637,6 +1642,8 @@ async fn start_maintenance_scheduler(
decay: crate::config::DecaySettings,
dream: crate::config::DreamSettings,
activity_clock: ai_memory_consolidate::ActivityClock,
+ contradiction_band_min: f32,
+ contradiction_band_max: f32,
) -> Vec<tokio::task::JoinHandle<()>> {
let maintenance_enabled = settings.enabled;
if !maintenance_enabled {
@@ -1799,9 +1806,15 @@ async fn start_maintenance_scheduler(
let decay_lambda = decay.decay_params().lambda;
async move {
let started = std::time::Instant::now();
- let outcome =
- run_scheduled_lint_tick(&reader, &wiki, llm.as_ref(), decay_lambda)
- .await?;
+ let outcome = run_scheduled_lint_tick(
+ &reader,
+ &wiki,
+ llm.as_ref(),
+ decay_lambda,
+ contradiction_band_min,
+ contradiction_band_max,
+ )
+ .await?;
if outcome.errors > 0 {
anyhow::bail!(
"scheduled rule-based lint had {} scope errors",
@@ -2185,6 +2198,8 @@ async fn run_scheduled_lint_tick(
wiki: &Wiki,
llm: Option<&Arc<dyn LlmProvider>>,
decay_lambda: f64,
+ contradiction_band_min: f32,
+ contradiction_band_max: f32,
) -> Result<ScheduledLintTickOutcome> {
let scopes = reader.list_all_scopes().await?;
let mut outcome = ScheduledLintTickOutcome {
@@ -2207,6 +2222,8 @@ async fn run_scheduled_lint_tick(
// contradiction detector is on for the user-invoked
// `memory_lint` / admin lint, not the background sweep.
embedding: None,
+ contradiction_band_min,
+ contradiction_band_max,
},
)
.await
@@ -3425,6 +3442,8 @@ mod tests {
crate::config::DecaySettings::default(),
crate::config::DreamSettings::default(),
ai_memory_consolidate::ActivityClock::default(),
+ ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
)
.await;
assert!(tasks.is_empty());
@@ -3471,6 +3490,8 @@ mod tests {
crate::config::DecaySettings::default(),
crate::config::DreamSettings::default(),
ai_memory_consolidate::ActivityClock::default(),
+ ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
)
.await;
// One enabled lint/sweep job plus the independent hollow-project job.
@@ -3968,6 +3989,8 @@ mod tests {
&wiki,
Some(&panic_llm),
ai_memory_store::DecayParams::default().lambda,
+ ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
)
.await
.unwrap();
diff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rs
index e059824a..9efebbca 100644
--- a/crates/ai-memory-cli/src/config.rs
+++ b/crates/ai-memory-cli/src/config.rs
@@ -491,6 +491,25 @@ pub struct Config {
pub decay: DecaySettings,
/// Server-side scheduled maintenance. Jobs run outside hook latency.
pub maintenance: MaintenanceSettings,
+ /// Lower edge (inclusive) of `memory_lint`'s A5 zero-LLM
+ /// contradiction-detection cosine-similarity band. Two cold pages whose
+ /// embeddings sit in `[contradiction_band_min, contradiction_band_max)`
+ /// are "same topic, not a duplicate" — flagged as a likely conflict.
+ ///
+ /// The band is a fixed absolute cosine value, but the background
+ /// similarity of unrelated pages is corpus-dependent: on a
+ /// single-language or single-domain store (or one written in a
+ /// non-English language), unrelated pages already sit well above the
+ /// general-purpose default floor, so the band ends up measuring domain
+ /// proximity rather than conflict and produces noisy findings. Raise
+ /// this floor for such a store. Default `0.4` preserves the historical
+ /// fixed band exactly. Settable via `AI_MEMORY_CONTRADICTION_BAND_MIN`.
+ pub contradiction_band_min: f32,
+ /// Upper edge (exclusive) of the band — see `contradiction_band_min`. At
+ /// or above this, two pages are treated as a near-duplicate (A3
+ /// cold-cluster dedup's territory) rather than a contradiction. Default
+ /// `0.75`. Settable via `AI_MEMORY_CONTRADICTION_BAND_MAX`.
+ pub contradiction_band_max: f32,
/// Opt-in LLM "dream" pass (B2/B3/B4): rewrite/merge cold clusters with the
/// configured provider, scheduled on idle and cancelled the moment the
/// operator returns. OFF by default and gated on an R2 number before it may
@@ -921,6 +940,8 @@ impl Default for Config {
embedding_document_prefix: None,
decay: DecaySettings::default(),
maintenance: MaintenanceSettings::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
dream: DreamSettings::default(),
retrieval: RetrievalSettings::default(),
slots: SlotSettings::default(),
@@ -1470,6 +1491,26 @@ impl Config {
if config.decay.observation_prune_batch == 0 {
anyhow::bail!("decay.observation_prune_batch must be greater than zero");
}
+ // A5 zero-LLM contradiction band (`memory_lint`): both edges must be
+ // finite and inside cosine similarity's own range, and the band must
+ // be non-empty. An inverted or out-of-range band would either
+ // silently disable A5 (no pair ever falls inside an empty range) or
+ // compare against a meaningless similarity value; reject it at load
+ // rather than inside the lint pass.
+ if !config.contradiction_band_min.is_finite()
+ || !config.contradiction_band_max.is_finite()
+ || config.contradiction_band_min < 0.0
+ || config.contradiction_band_max > 1.0
+ || config.contradiction_band_min >= config.contradiction_band_max
+ {
+ anyhow::bail!(
+ "contradiction_band_min/contradiction_band_max must satisfy \
+ 0.0 <= contradiction_band_min < contradiction_band_max <= 1.0 \
+ (got min={}, max={})",
+ config.contradiction_band_min,
+ config.contradiction_band_max
+ );
+ }
// A4 entropy filter thresholds: reject an unusable threshold at startup
// rather than silently ignoring it on the first experience pass.
if let Err(message) = config
@@ -2639,6 +2680,48 @@ mod tests {
);
}
+ /// An install that never touched `contradiction_band_min`/`_max` sees no
+ /// change: the defaults are exactly the historical fixed band.
+ #[test]
+ fn contradiction_band_defaults_match_the_historical_fixed_band() {
+ let cfg = Config::default();
+ assert_eq!(
+ cfg.contradiction_band_min,
+ ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW
+ );
+ assert_eq!(
+ cfg.contradiction_band_max,
+ ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH
+ );
+ }
+
+ #[test]
+ fn load_rejects_invalid_contradiction_band() {
+ for (min, max) in [
+ ("0.8", "0.4"), // min >= max (inverted)
+ ("0.4", "0.4"), // min >= max (equal)
+ ("-0.1", "0.75"), // min out of range
+ ("0.4", "1.5"), // max out of range
+ ("nan", "0.75"), // NaN
+ ("0.4", "nan"), // NaN
+ ("0.4", "inf"), // infinite (not finite)
+ ] {
+ let tmp = TempDir::new().unwrap();
+ let config_path = tmp.path().join("config.toml");
+ std::fs::write(
+ &config_path,
+ format!("contradiction_band_min = {min}\ncontradiction_band_max = {max}\n"),
+ )
+ .unwrap();
+ let error = Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))
+ .expect_err(&format!("min={min} max={max} must fail closed"));
+ assert!(
+ error.to_string().contains("contradiction_band"),
+ "unexpected error for min={min} max={max}: {error:#}"
+ );
+ }
+ }
+
#[test]
fn load_rejects_destructive_invalid_breadth_weights() {
for value in ["-0.1", "nan", "inf"] {
@@ -3064,6 +3147,8 @@ mod tests {
log_level = "debug"
hook_rate_per_sec = 7.5
hook_rate_burst = 12.0
+ contradiction_band_min = 0.5
+ contradiction_band_max = 0.8
[auth]
secure_cookie = true
@@ -3119,6 +3204,8 @@ mod tests {
assert_eq!(cfg.log_level, "debug");
assert_eq!(cfg.hook_rate_per_sec, 7.5);
assert_eq!(cfg.hook_rate_burst, 12.0);
+ assert_eq!(cfg.contradiction_band_min, 0.5);
+ assert_eq!(cfg.contradiction_band_max, 0.8);
assert!(cfg.auth.secure_cookie);
assert!(!cfg.maintenance.enabled);
assert_eq!(cfg.maintenance.lint_interval_secs, 3600);
diff --git a/crates/ai-memory-consolidate/src/lib.rs b/crates/ai-memory-consolidate/src/lib.rs
index b15eca15..14fe6f5f 100644
--- a/crates/ai-memory-consolidate/src/lib.rs
+++ b/crates/ai-memory-consolidate/src/lib.rs
@@ -80,7 +80,10 @@ pub use embed::{
pub use entropy_filter::{EntropyFilterConfig, FilterVerdict, SkipReason, classify};
pub use experience::{EXPERIENCE_SYSTEM_PROMPT, ExperienceConfig, run_experience_review};
pub use keep_tokens::mine_keep_tokens;
-pub use lint::{LintError, LintFinding, LintOptions, LintReport, run_lint, stale_days_for};
+pub use lint::{
+ DEFAULT_CONTRADICTION_SIM_HIGH, DEFAULT_CONTRADICTION_SIM_LOW, LintError, LintFinding,
+ LintOptions, LintReport, run_lint, stale_days_for,
+};
pub use sweep::{
ColdClusterDedup, CompactedPage, DEFAULT_OBSERVATION_PRUNE_BATCH, EmbeddingCoord, EvictedPage,
MergedCluster, ObservationRetention, SweepError, SweepReport, run_sweep,
diff --git a/crates/ai-memory-consolidate/src/lint.rs b/crates/ai-memory-consolidate/src/lint.rs
index 7671c8a2..6e0453d4 100644
--- a/crates/ai-memory-consolidate/src/lint.rs
+++ b/crates/ai-memory-consolidate/src/lint.rs
@@ -147,11 +147,20 @@ pub struct LintOptions {
/// The running embedder's `(provider, model, dim)` triple, or `None` when
/// no embedder is configured. It drives the zero-LLM contradiction
/// detector (A5): the detector loads already-stored vectors under this
- /// triple and flags pages in the 0.4–0.75 cosine-similarity band. `None`
- /// makes that pass a clean no-op. User-invoked lint paths supply it; the
+ /// triple and flags pages in the `[contradiction_band_min,
+ /// contradiction_band_max)` cosine-similarity band. `None` makes that
+ /// pass a clean no-op. User-invoked lint paths supply it; the
/// automatic scheduled lint passes `None` — detection is on for the
/// user-invoked operation, not the background sweep.
pub embedding: Option<EmbeddingCoord>,
+ /// Lower edge (inclusive) of the A5 contradiction-similarity band. See
+ /// [`DEFAULT_CONTRADICTION_SIM_LOW`] for the historical default and why
+ /// an operator might raise it (same-domain / non-English corpora, where
+ /// the background similarity floor sits well above 0.4).
+ pub contradiction_band_min: f32,
+ /// Upper edge (exclusive) of the A5 contradiction-similarity band. See
+ /// [`DEFAULT_CONTRADICTION_SIM_HIGH`].
+ pub contradiction_band_max: f32,
}
impl Default for LintOptions {
@@ -161,6 +170,8 @@ impl Default for LintOptions {
use_llm: true,
decay_lambda: 0.02,
embedding: None,
+ contradiction_band_min: DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: DEFAULT_CONTRADICTION_SIM_HIGH,
}
}
}
@@ -191,6 +202,8 @@ pub async fn run_lint(
use_llm,
decay_lambda,
embedding,
+ contradiction_band_min,
+ contradiction_band_max,
} = options;
let candidates = reader.decay_candidates(workspace_id, project_id).await?;
let mut findings = rule_based_findings(&candidates, stale_days_for(decay_lambda));
@@ -284,11 +297,18 @@ pub async fn run_lint(
}
// Zero-LLM detected contradictions (A5): pages whose embeddings sit in the
- // 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.
+ // (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.
+ //
+ // The band is a FIXED absolute cosine value, but background similarity is
+ // corpus-dependent: on a single-language or single-domain store, unrelated
+ // pages already sit well above the general-purpose 0.4 floor, so the
+ // default band measures domain proximity more than conflict and produces
+ // noisy findings. Raise `contradiction_band_min` for such a store.
//
// Why no persistence / no migration: a `contradicts` edge would live in the
// `links` table, but `links` rows are BODY-DERIVED — `replace_links_in_tx`
@@ -302,6 +322,8 @@ pub async fn run_lint(
project_id,
&candidates,
embedding.as_ref(),
+ contradiction_band_min,
+ contradiction_band_max,
)
.await
{
@@ -453,14 +475,24 @@ fn rule_based_findings(candidates: &[DecayCandidate], stale_days: f64) -> Vec<Li
// ── A5: zero-LLM contradiction detection (cosine-similarity band) ──────────
-/// Lower edge (inclusive) of the likely-contradiction cosine-similarity band.
-/// Below this two pages are simply unrelated (different topics).
-const CONTRADICTION_SIM_LOW: f32 = 0.4;
-/// Upper edge (exclusive) of the band. At or above this two pages are a
+/// Default lower edge (inclusive) of the likely-contradiction cosine-similarity
+/// band. Below this two pages are simply unrelated (different topics).
+///
+/// Configurable (`contradiction_band_min` / `AI_MEMORY_CONTRADICTION_BAND_MIN`)
+/// because this floor is a fixed absolute cosine value, but the *background*
+/// similarity of unrelated pages is corpus-dependent: a single-language or
+/// single-domain store sits well above general-purpose background similarity,
+/// so the fixed 0.4 floor admits many same-domain-but-unrelated pairs as
+/// "likely contradictions". Raising the floor trims that noise; the default
+/// preserves the historical fixed band exactly.
+pub const DEFAULT_CONTRADICTION_SIM_LOW: f32 = 0.4;
+/// Default upper edge (exclusive) of the band. At or above this two pages are a
/// near-duplicate — A3 cold-cluster dedup's territory, not a contradiction.
/// The band (mcp-memory-service's heuristic) is "same topic, not a duplicate":
/// the shape of two pages that discuss the same thing while likely disagreeing.
-const CONTRADICTION_SIM_HIGH: f32 = 0.75;
+/// Configurable via `contradiction_band_max` /
+/// `AI_MEMORY_CONTRADICTION_BAND_MAX` — see [`DEFAULT_CONTRADICTION_SIM_LOW`].
+pub const DEFAULT_CONTRADICTION_SIM_HIGH: f32 = 0.75;
/// Cap on cold pages fed to the pairwise scan. The scan is O(N²) cosine ops, so
/// this bounds it hard on the already-bounded cold set (invariant #2 — one
/// embeddings load, no per-page N+1).
@@ -469,10 +501,13 @@ const CONTRADICTION_MAX_PAGES: usize = 60;
/// many pairs in the band cannot flood the advisory report.
const CONTRADICTION_MAX_FINDINGS: usize = 25;
-/// Whether a cosine similarity falls in the likely-contradiction band.
+/// Whether a cosine similarity falls in the likely-contradiction band
+/// `[low, high)`. `low`/`high` are normally
+/// [`DEFAULT_CONTRADICTION_SIM_LOW`]/[`DEFAULT_CONTRADICTION_SIM_HIGH`],
+/// overridden by `contradiction_band_min`/`contradiction_band_max`.
#[must_use]
-fn in_contradiction_band(similarity: f32) -> bool {
- (CONTRADICTION_SIM_LOW..CONTRADICTION_SIM_HIGH).contains(&similarity)
+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
@@ -485,7 +520,7 @@ struct BandCandidate {
/// 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 `[0.4, 0.75)`, capped at `max_findings`.
+/// 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
@@ -493,13 +528,15 @@ struct BandCandidate {
/// input always yields the same capped subset.
fn detected_contradiction_findings(
pages: &[BandCandidate],
+ band_min: f32,
+ band_max: f32,
max_findings: usize,
) -> Vec<LintFinding> {
let mut findings = Vec::new();
'outer: for i in 0..pages.len() {
for j in (i + 1)..pages.len() {
let similarity = 1.0 - cosine_distance(&pages[i].vector, &pages[j].vector);
- if !in_contradiction_band(similarity) {
+ if !in_contradiction_band(similarity, band_min, band_max) {
continue;
}
let (a, b) = (&pages[i], &pages[j]);
@@ -546,6 +583,8 @@ async fn detected_contradiction_pass(
project_id: ProjectId,
candidates: &[DecayCandidate],
embedding: Option<&EmbeddingCoord>,
+ band_min: f32,
+ band_max: f32,
) -> Result<Vec<LintFinding>, LintError> {
let Some(coord) = embedding else {
return Ok(Vec::new());
@@ -606,6 +645,8 @@ async fn detected_contradiction_pass(
Ok(detected_contradiction_findings(
&pages,
+ band_min,
+ band_max,
CONTRADICTION_MAX_FINDINGS,
))
}
@@ -1111,18 +1152,54 @@ mod tests {
/// unrelated pair (<0.4) are not.
#[test]
fn contradiction_band_predicate() {
- assert!(in_contradiction_band(0.6), "0.6 is the band's centre");
- assert!(in_contradiction_band(0.4), "0.4 is the inclusive low edge");
+ let (low, high) = (
+ DEFAULT_CONTRADICTION_SIM_LOW,
+ DEFAULT_CONTRADICTION_SIM_HIGH,
+ );
assert!(
- !in_contradiction_band(0.75),
+ in_contradiction_band(0.6, low, high),
+ "0.6 is the band's centre"
+ );
+ assert!(
+ in_contradiction_band(0.4, low, high),
+ "0.4 is the inclusive low edge"
+ );
+ assert!(
+ !in_contradiction_band(0.75, low, high),
"0.75 is a near-duplicate (A3 dedup), not a contradiction"
);
assert!(
- !in_contradiction_band(0.85),
+ !in_contradiction_band(0.85, low, high),
"0.85 is a near-duplicate, not a contradiction"
);
- assert!(!in_contradiction_band(0.2), "0.2 is unrelated");
- assert!(!in_contradiction_band(1.0), "identical is a duplicate");
+ assert!(!in_contradiction_band(0.2, low, high), "0.2 is unrelated");
+ assert!(
+ !in_contradiction_band(1.0, low, high),
+ "identical is a duplicate"
+ );
+ }
+
+ /// Raising the floor (e.g. for a single-domain corpus) suppresses a pair
+ /// that the default 0.4 floor would admit: a 0.7 pair sits inside the
+ /// default band but outside a raised 0.8 floor.
+ #[test]
+ fn contradiction_band_predicate_with_custom_bounds() {
+ assert!(
+ in_contradiction_band(
+ 0.7,
+ DEFAULT_CONTRADICTION_SIM_LOW,
+ DEFAULT_CONTRADICTION_SIM_HIGH
+ ),
+ "0.7 is inside the default 0.4-0.75 band"
+ );
+ assert!(
+ !in_contradiction_band(0.7, 0.8, DEFAULT_CONTRADICTION_SIM_HIGH),
+ "0.7 is below a raised 0.8 floor"
+ );
+ assert!(
+ in_contradiction_band(0.82, 0.8, 0.9),
+ "0.82 is inside a custom 0.8-0.9 band"
+ );
}
// Unit-length 2-D vectors: cosine similarity between them equals the dot
@@ -1144,7 +1221,12 @@ mod tests {
// 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]),
];
- let findings = detected_contradiction_findings(&pages, CONTRADICTION_MAX_FINDINGS);
+ let findings = detected_contradiction_findings(
+ &pages,
+ DEFAULT_CONTRADICTION_SIM_LOW,
+ DEFAULT_CONTRADICTION_SIM_HIGH,
+ CONTRADICTION_MAX_FINDINGS,
+ );
assert_eq!(
findings.len(),
1,
@@ -1173,13 +1255,53 @@ mod tests {
// dot ≈ 0.98 — a near-duplicate, above the band.
band("concepts/b.md", 2, vec![0.98, 0.199]),
];
- let findings = detected_contradiction_findings(&pages, CONTRADICTION_MAX_FINDINGS);
+ let findings = detected_contradiction_findings(
+ &pages,
+ DEFAULT_CONTRADICTION_SIM_LOW,
+ DEFAULT_CONTRADICTION_SIM_HIGH,
+ CONTRADICTION_MAX_FINDINGS,
+ );
assert!(
findings.is_empty(),
"near-duplicate must not be flagged as a contradiction: {findings:?}"
);
}
+ /// A pair at cosine 0.7 sits inside the default 0.4-0.75 band (flagged),
+ /// but a raised 0.8 floor — the fix for a same-domain / non-English store
+ /// where 0.7 is just background domain proximity, not a likely conflict —
+ /// drops it.
+ #[test]
+ fn band_scan_raised_floor_drops_a_same_domain_pair() {
+ // 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]),
+ ];
+ let default_findings = detected_contradiction_findings(
+ &pages,
+ DEFAULT_CONTRADICTION_SIM_LOW,
+ DEFAULT_CONTRADICTION_SIM_HIGH,
+ CONTRADICTION_MAX_FINDINGS,
+ );
+ assert_eq!(
+ default_findings.len(),
+ 1,
+ "the default 0.4 floor admits a 0.7 same-domain pair: {default_findings:?}"
+ );
+ let raised_findings = detected_contradiction_findings(
+ &pages,
+ 0.8,
+ DEFAULT_CONTRADICTION_SIM_HIGH,
+ CONTRADICTION_MAX_FINDINGS,
+ );
+ assert!(
+ raised_findings.is_empty(),
+ "a raised 0.8 floor must drop the 0.7 same-domain pair: {raised_findings:?}"
+ );
+ }
+
/// An unrelated pair (cosine ≈ 0.2) is below the band, never flagged.
#[test]
fn band_scan_ignores_unrelated_pairs() {
@@ -1187,7 +1309,12 @@ mod tests {
band("concepts/a.md", 1, vec![1.0, 0.0]),
band("concepts/b.md", 2, vec![0.2, 0.9798]),
];
- let findings = detected_contradiction_findings(&pages, CONTRADICTION_MAX_FINDINGS);
+ let findings = detected_contradiction_findings(
+ &pages,
+ DEFAULT_CONTRADICTION_SIM_LOW,
+ DEFAULT_CONTRADICTION_SIM_HIGH,
+ CONTRADICTION_MAX_FINDINGS,
+ );
assert!(
findings.is_empty(),
"unrelated pair not flagged: {findings:?}"
@@ -1197,9 +1324,25 @@ mod tests {
/// Empty and single-page inputs produce nothing (no pair to compare).
#[test]
fn band_scan_handles_empty_and_single() {
- assert!(detected_contradiction_findings(&[], CONTRADICTION_MAX_FINDINGS).is_empty());
+ assert!(
+ detected_contradiction_findings(
+ &[],
+ DEFAULT_CONTRADICTION_SIM_LOW,
+ DEFAULT_CONTRADICTION_SIM_HIGH,
+ CONTRADICTION_MAX_FINDINGS
+ )
+ .is_empty()
+ );
let one = vec![band("concepts/a.md", 1, vec![1.0, 0.0])];
- assert!(detected_contradiction_findings(&one, CONTRADICTION_MAX_FINDINGS).is_empty());
+ assert!(
+ detected_contradiction_findings(
+ &one,
+ DEFAULT_CONTRADICTION_SIM_LOW,
+ DEFAULT_CONTRADICTION_SIM_HIGH,
+ CONTRADICTION_MAX_FINDINGS
+ )
+ .is_empty()
+ );
}
/// The findings cap is honoured: two in-band pairs, cap of 1 ⇒ one finding.
@@ -1217,12 +1360,24 @@ mod tests {
band("concepts/c.md", 3, vec![c.cos() as f32, c.sin() as f32]),
];
assert_eq!(
- detected_contradiction_findings(&pages, CONTRADICTION_MAX_FINDINGS).len(),
+ detected_contradiction_findings(
+ &pages,
+ DEFAULT_CONTRADICTION_SIM_LOW,
+ DEFAULT_CONTRADICTION_SIM_HIGH,
+ CONTRADICTION_MAX_FINDINGS
+ )
+ .len(),
2,
"two adjacent pairs are in band"
);
assert_eq!(
- detected_contradiction_findings(&pages, 1).len(),
+ detected_contradiction_findings(
+ &pages,
+ DEFAULT_CONTRADICTION_SIM_LOW,
+ DEFAULT_CONTRADICTION_SIM_HIGH,
+ 1
+ )
+ .len(),
1,
"a cap of 1 truncates the two candidate pairs"
);
diff --git a/crates/ai-memory-consolidate/tests/suite/aging_lifecycle.rs b/crates/ai-memory-consolidate/tests/suite/aging_lifecycle.rs
index 46b1b395..5780f797 100644
--- a/crates/ai-memory-consolidate/tests/suite/aging_lifecycle.rs
+++ b/crates/ai-memory-consolidate/tests/suite/aging_lifecycle.rs
@@ -731,6 +731,8 @@ async fn s1_contradiction_lint_flags_band_pair_without_deleting() {
model: MODEL.into(),
dim: 2,
}),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
},
)
.await
diff --git a/crates/ai-memory-consolidate/tests/suite/contradiction_lint.rs b/crates/ai-memory-consolidate/tests/suite/contradiction_lint.rs
index db7fcde6..7e0f6a19 100644
--- a/crates/ai-memory-consolidate/tests/suite/contradiction_lint.rs
+++ b/crates/ai-memory-consolidate/tests/suite/contradiction_lint.rs
@@ -120,6 +120,18 @@ fn latest_page_count(fx: &Fixture) -> i64 {
}
fn options(embedding: Option<EmbeddingCoord>) -> LintOptions {
+ options_with_band(
+ embedding,
+ ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
+ )
+}
+
+fn options_with_band(
+ embedding: Option<EmbeddingCoord>,
+ band_min: f32,
+ band_max: f32,
+) -> LintOptions {
LintOptions {
// dry_run so the pass emits findings without writing a report page,
// keeping the "nothing was mutated" assertion clean.
@@ -128,6 +140,8 @@ fn options(embedding: Option<EmbeddingCoord>) -> LintOptions {
use_llm: false,
decay_lambda: 0.02,
embedding,
+ contradiction_band_min: band_min,
+ contradiction_band_max: band_max,
}
}
@@ -197,6 +211,39 @@ async fn band_pair_yields_advisory_contradiction() {
);
}
+/// A raised floor (as a same-domain / non-English store would configure)
+/// suppresses the same 0.6-similarity pair the default 0.4 floor admits.
+#[tokio::test]
+async fn raised_floor_suppresses_the_band_pair_end_to_end() {
+ 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 — inside the default band, below a 0.7 floor.
+ seed_embedding(&fx, old, &[1.0, 0.0]);
+ seed_embedding(&fx, new, &[0.6, 0.8]);
+
+ let report = run_lint(
+ &fx.store.reader,
+ &fx.wiki,
+ None,
+ fx.ws,
+ fx.proj,
+ options_with_band(
+ coord(),
+ 0.7,
+ ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
+ ),
+ )
+ .await
+ .unwrap();
+
+ assert!(
+ !report.findings.iter().any(|f| f.kind == "contradiction"),
+ "a 0.7 floor must drop the 0.6-similarity pair the default 0.4 floor admits: {:?}",
+ report.findings
+ );
+}
+
/// A near-duplicate pair (cosine ≈ 0.98) is A3's dedup job, not a
/// contradiction — the detector must stay silent.
#[tokio::test]
diff --git a/crates/ai-memory-consolidate/tests/suite/lifecycle.rs b/crates/ai-memory-consolidate/tests/suite/lifecycle.rs
index 11cd582f..590b6276 100644
--- a/crates/ai-memory-consolidate/tests/suite/lifecycle.rs
+++ b/crates/ai-memory-consolidate/tests/suite/lifecycle.rs
@@ -430,6 +430,8 @@ async fn m8_retention_lifecycle_end_to_end() {
use_llm: true,
decay_lambda: ai_memory_store::DecayParams::default().lambda,
embedding: None,
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
},
)
.await
diff --git a/crates/ai-memory-consolidate/tests/suite/typed_edges.rs b/crates/ai-memory-consolidate/tests/suite/typed_edges.rs
index d48c5f1e..f78dfc17 100644
--- a/crates/ai-memory-consolidate/tests/suite/typed_edges.rs
+++ b/crates/ai-memory-consolidate/tests/suite/typed_edges.rs
@@ -126,6 +126,8 @@ async fn a_declared_contradiction_is_a_lint_finding_without_an_llm() {
use_llm: false,
decay_lambda: 0.02,
embedding: None,
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
},
)
.await
@@ -172,6 +174,8 @@ async fn a_contradiction_to_a_deleted_page_reports_the_stale_declaration() {
use_llm: false,
decay_lambda: 0.02,
embedding: None,
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
},
)
.await
@@ -238,6 +242,8 @@ async fn lint_supersedes_one_report_and_prunes_the_legacy_daily_pile() {
use_llm: false,
decay_lambda: 0.02,
embedding: None,
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
};
let report = run_lint(&store.reader, &wiki, None, ws, proj, opts.clone())
.await
@@ -288,6 +294,8 @@ async fn a_clean_pass_removes_the_stale_report() {
use_llm: false,
decay_lambda: 0.02,
embedding: None,
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
};
run_lint(&store.reader, &wiki, None, ws, proj, opts.clone())
.await
diff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rs
index 1a047d3c..54562feb 100644
--- a/crates/ai-memory-mcp/src/admin.rs
+++ b/crates/ai-memory-mcp/src/admin.rs
@@ -126,6 +126,13 @@ pub struct AdminState {
pub ingest_metrics: std::sync::Arc<ai_memory_core::IngestMetrics>,
/// Retention-decay parameters forwarded from server config.
pub decay_params: DecayParams,
+ /// Lower edge of `memory_lint`'s A5 zero-LLM contradiction-similarity
+ /// band, forwarded from `config.contradiction_band_min`. Defaults to
+ /// [`ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW`].
+ pub contradiction_band_min: f32,
+ /// Upper edge of the A5 band — see `contradiction_band_min`. Defaults to
+ /// [`ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH`].
+ pub contradiction_band_max: f32,
/// Server's resolved data directory (e.g. `/data` in the docker
/// image). Surfaced via `/admin/status` so the CLI can report
/// "where the wiki + db actually live".
@@ -3487,6 +3494,8 @@ async fn handle_lint(
model: e.model_identity(),
dim: e.dim(),
}),
+ contradiction_band_min: state.contradiction_band_min,
+ contradiction_band_max: state.contradiction_band_max,
},
)
.await
@@ -7713,6 +7722,8 @@ mod tests {
embedder: None,
provider_health: ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path: store.db_path().to_path_buf(),
bind: "127.0.0.1:49374".to_string(),
@@ -7780,6 +7791,8 @@ mod tests {
embedder: None,
provider_health: ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path: store.db_path().to_path_buf(),
bind: "127.0.0.1:49376".to_string(),
@@ -7903,6 +7916,8 @@ mod tests {
embedder: None,
provider_health: ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path: store.db_path().to_path_buf(),
bind: "127.0.0.1:49375".to_string(),
@@ -8137,6 +8152,8 @@ mod tests {
embedder: None,
provider_health: ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path: store.db_path().to_path_buf(),
bind: "127.0.0.1:49374".to_string(),
@@ -8331,6 +8348,8 @@ mod tests {
embedder: None,
provider_health: ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path: store.db_path().to_path_buf(),
bind: "127.0.0.1:49374".to_string(),
@@ -8552,6 +8571,8 @@ mod tests {
embedder: None,
provider_health: ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path: store.db_path().to_path_buf(),
bind: "127.0.0.1:49374".to_string(),
@@ -8909,6 +8930,8 @@ mod tests {
embedder: None,
provider_health: ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path: store.db_path().to_path_buf(),
bind: "127.0.0.1:49374".to_string(),
@@ -10397,6 +10420,8 @@ mod tests {
embedder: None,
provider_health: ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path: store.db_path().to_path_buf(),
bind: "127.0.0.1:49374".to_string(),
@@ -10507,6 +10532,8 @@ mod tests {
embedder: None,
provider_health: ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path: store.db_path().to_path_buf(),
bind: "127.0.0.1:49374".to_string(),
@@ -10610,6 +10637,8 @@ mod tests {
embedder: None,
provider_health: ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path: store.db_path().to_path_buf(),
bind: "127.0.0.1:49374".to_string(),
@@ -10719,6 +10748,8 @@ mod tests {
embedder: None,
provider_health: ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path: store.db_path().to_path_buf(),
bind: "127.0.0.1:49374".to_string(),
@@ -11267,6 +11298,8 @@ mod tests {
embedder: None,
provider_health: ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path: store.db_path().to_path_buf(),
bind: "127.0.0.1:49374".to_string(),
@@ -11324,6 +11357,8 @@ mod tests {
embedder: None,
provider_health: ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path: store.db_path().to_path_buf(),
bind: "127.0.0.1:49374".to_string(),
@@ -11760,6 +11795,8 @@ mod tests {
embedder: None,
provider_health: ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path: store.db_path().to_path_buf(),
bind: "127.0.0.1:49374".to_string(),
@@ -11892,6 +11929,8 @@ mod tests {
embedder: None,
provider_health: ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path: store.db_path().to_path_buf(),
bind: "127.0.0.1:49374".to_string(),
@@ -12323,6 +12362,8 @@ mod tests {
embedder: None,
provider_health: ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path: store.db_path().to_path_buf(),
bind: "127.0.0.1:49374".to_string(),
diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rs
index f8cdd360..44539bce 100644
--- a/crates/ai-memory-mcp/src/server.rs
+++ b/crates/ai-memory-mcp/src/server.rs
@@ -460,6 +460,13 @@ pub struct AiMemoryServer {
/// A2 opt-in: compact cold episodic pages (tier-down) instead of evicting
/// them. Default `false`, so the sweep evicts exactly as before.
compact_cold_episodic: bool,
+ /// Lower edge of `memory_lint`'s A5 zero-LLM contradiction-similarity
+ /// band, from `config.contradiction_band_min`. Defaults to
+ /// [`ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW`].
+ contradiction_band_min: f32,
+ /// Upper edge of the A5 band — see `contradiction_band_min`. Defaults to
+ /// [`ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH`].
+ contradiction_band_max: f32,
/// M9 embedder for hybrid query. When `None`, `memory_query`
/// still fuses FTS5 with entity matches and graph-neighbour expansion.
embedder: Option<Arc<dyn Embedder>>,
@@ -1640,6 +1647,8 @@ impl AiMemoryServer {
decay_breadth_weight: 0.0,
observation_retention: ObservationRetention::default(),
compact_cold_episodic: false,
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
embedder: None,
reranker: None,
client_activity: Arc::new(std::sync::Mutex::new(ClientActivityBuffer::new())),
@@ -2272,6 +2281,18 @@ impl AiMemoryServer {
self
}
+ /// Override the A5 zero-LLM contradiction-similarity band (typically
+ /// populated from `config.contradiction_band_min`/`_max`). Unset, it
+ /// defaults to the historical fixed band (see
+ /// [`ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW`] /
+ /// [`ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH`]).
+ #[must_use]
+ pub fn with_contradiction_band(mut self, min: f32, max: f32) -> Self {
+ self.contradiction_band_min = min;
+ self.contradiction_band_max = max;
+ self
+ }
+
/// Set the opt-in observation prune bound used by `memory_forget_sweep`.
/// Unset, the sweep never deletes a raw observation.
#[must_use]
@@ -3134,6 +3155,8 @@ impl AiMemoryServer {
model: e.model_identity(),
dim: e.dim(),
}),
+ contradiction_band_min: self.contradiction_band_min,
+ contradiction_band_max: self.contradiction_band_max,
},
)
.await
diff --git a/crates/ai-memory-mcp/tests/suite/admin_audit_log.rs b/crates/ai-memory-mcp/tests/suite/admin_audit_log.rs
index 99ca92f6..9e89f06d 100644
--- a/crates/ai-memory-mcp/tests/suite/admin_audit_log.rs
+++ b/crates/ai-memory-mcp/tests/suite/admin_audit_log.rs
@@ -24,6 +24,8 @@ async fn make_admin_state(tmp: &TempDir) -> (AdminState, Store) {
embedder: None,
provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path,
bind: "127.0.0.1:49374".to_string(),
diff --git a/crates/ai-memory-mcp/tests/suite/admin_backup.rs b/crates/ai-memory-mcp/tests/suite/admin_backup.rs
index bdb474e7..006c7530 100644
--- a/crates/ai-memory-mcp/tests/suite/admin_backup.rs
+++ b/crates/ai-memory-mcp/tests/suite/admin_backup.rs
@@ -34,6 +34,8 @@ async fn make_state(tmp: &TempDir) -> (AdminState, Store) {
embedder: None,
provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path,
bind: "127.0.0.1:0".to_string(),
diff --git a/crates/ai-memory-mcp/tests/suite/admin_bootstrap.rs b/crates/ai-memory-mcp/tests/suite/admin_bootstrap.rs
index a7700657..8fda091b 100644
--- a/crates/ai-memory-mcp/tests/suite/admin_bootstrap.rs
+++ b/crates/ai-memory-mcp/tests/suite/admin_bootstrap.rs
@@ -31,6 +31,8 @@ async fn make_admin_state(tmp: &TempDir) -> AdminState {
embedder: None,
provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path,
bind: "127.0.0.1:0".to_string(),
diff --git a/crates/ai-memory-mcp/tests/suite/admin_move.rs b/crates/ai-memory-mcp/tests/suite/admin_move.rs
index 32cc65b0..ee46a2db 100644
--- a/crates/ai-memory-mcp/tests/suite/admin_move.rs
+++ b/crates/ai-memory-mcp/tests/suite/admin_move.rs
@@ -49,6 +49,8 @@ async fn make_state(tmp: &TempDir) -> (AdminState, Store) {
embedder: None,
provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path,
bind: "127.0.0.1:0".to_string(),
@@ -80,6 +82,8 @@ async fn make_state_with_chain(tmp: &TempDir, chain: AdmissionChain) -> (AdminSt
embedder: None,
provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path,
bind: "127.0.0.1:0".to_string(),
@@ -453,6 +457,8 @@ async fn move_project_carries_source_embedding() {
embedder: Some(embedder),
provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path,
bind: "127.0.0.1:0".to_string(),
@@ -744,6 +750,8 @@ async fn true_move_notifies_admission_with_destination_names() {
embedder: None,
provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path: store.db_path().to_path_buf(),
bind: "127.0.0.1:0".to_string(),
@@ -800,6 +808,8 @@ async fn make_state_with_embedder(tmp: &TempDir) -> (AdminState, Store) {
embedder: Some(embedder),
provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path,
bind: "127.0.0.1:0".to_string(),
@@ -1029,6 +1039,8 @@ fn build_state(store: &Store, tmp: &TempDir) -> AdminState {
embedder: None,
provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path: store.db_path().to_path_buf(),
bind: "127.0.0.1:0".to_string(),
@@ -1527,6 +1539,8 @@ async fn true_move_aborts_when_admission_rejects() {
embedder: None,
provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path: store.db_path().to_path_buf(),
bind: "127.0.0.1:0".to_string(),
@@ -1624,6 +1638,8 @@ async fn copy_purge_purge_admission_runs_before_db_destruction() {
embedder: None,
provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path: store.db_path().to_path_buf(),
bind: "127.0.0.1:0".to_string(),
@@ -1738,6 +1754,8 @@ async fn move_copy_skips_contributors_webhook_but_runs_others() {
embedder: None,
provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path: store.db_path().to_path_buf(),
bind: "127.0.0.1:0".to_string(),
diff --git a/crates/ai-memory-mcp/tests/suite/admin_move_session.rs b/crates/ai-memory-mcp/tests/suite/admin_move_session.rs
index 6bb9994f..24f54945 100644
--- a/crates/ai-memory-mcp/tests/suite/admin_move_session.rs
+++ b/crates/ai-memory-mcp/tests/suite/admin_move_session.rs
@@ -41,6 +41,8 @@ async fn make_state(tmp: &TempDir) -> (AdminState, Store) {
embedder: None,
provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path,
bind: "127.0.0.1:0".to_string(),
diff --git a/crates/ai-memory-mcp/tests/suite/admin_phase3.rs b/crates/ai-memory-mcp/tests/suite/admin_phase3.rs
index 73c9f43c..89867096 100644
--- a/crates/ai-memory-mcp/tests/suite/admin_phase3.rs
+++ b/crates/ai-memory-mcp/tests/suite/admin_phase3.rs
@@ -47,6 +47,8 @@ async fn make_state(tmp: &TempDir) -> (AdminState, Store) {
embedder: None,
provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path,
bind: "127.0.0.1:0".to_string(),
diff --git a/crates/ai-memory-mcp/tests/suite/admin_provider_error_logging.rs b/crates/ai-memory-mcp/tests/suite/admin_provider_error_logging.rs
index 12717403..d807a19a 100644
--- a/crates/ai-memory-mcp/tests/suite/admin_provider_error_logging.rs
+++ b/crates/ai-memory-mcp/tests/suite/admin_provider_error_logging.rs
@@ -102,6 +102,8 @@ async fn make_admin_state(tmp: &TempDir, llm: Option<Arc<dyn LlmProvider>>) -> A
embedder: None,
provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path,
bind: "127.0.0.1:0".to_string(),
diff --git a/crates/ai-memory-mcp/tests/suite/admin_purge.rs b/crates/ai-memory-mcp/tests/suite/admin_purge.rs
index 3ad4d5d3..9342af2b 100644
--- a/crates/ai-memory-mcp/tests/suite/admin_purge.rs
+++ b/crates/ai-memory-mcp/tests/suite/admin_purge.rs
@@ -50,6 +50,8 @@ async fn make_state_with_chain(
embedder: None,
provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
bind: "127.0.0.1:0".to_string(),
home_dir: None,
@@ -659,6 +661,8 @@ async fn purge_project_rejecting_admission_leaves_source_intact() {
embedder: None,
provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path: store.db_path().to_path_buf(),
bind: "127.0.0.1:0".to_string(),
@@ -762,6 +766,8 @@ async fn purge_project_idempotent_second_call_is_404() {
embedder: None,
provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path: store.db_path().to_path_buf(),
bind: "127.0.0.1:0".to_string(),
diff --git a/crates/ai-memory-mcp/tests/suite/admin_read_page.rs b/crates/ai-memory-mcp/tests/suite/admin_read_page.rs
index 95d3c675..a9649189 100644
--- a/crates/ai-memory-mcp/tests/suite/admin_read_page.rs
+++ b/crates/ai-memory-mcp/tests/suite/admin_read_page.rs
@@ -26,6 +26,8 @@ async fn make_state(tmp: &TempDir) -> (AdminState, Store) {
embedder: None,
provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path,
bind: "127.0.0.1:49374".to_string(),
diff --git a/crates/ai-memory-mcp/tests/suite/admin_rename.rs b/crates/ai-memory-mcp/tests/suite/admin_rename.rs
index e14ee18e..2be83a48 100644
--- a/crates/ai-memory-mcp/tests/suite/admin_rename.rs
+++ b/crates/ai-memory-mcp/tests/suite/admin_rename.rs
@@ -34,6 +34,8 @@ async fn make_state(tmp: &TempDir) -> (AdminState, Store) {
embedder: None,
provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path,
bind: "127.0.0.1:0".to_string(),
@@ -314,6 +316,8 @@ async fn rename_project_pages_still_searchable() {
embedder: None,
provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path: store.db_path().to_path_buf(),
bind: "127.0.0.1:0".to_string(),
@@ -388,6 +392,8 @@ async fn rename_project_after_purge_returns_404_not_silent_200() {
embedder: state.embedder.clone(),
provider_health: state.provider_health.clone(),
decay_params: state.decay_params,
+ contradiction_band_min: state.contradiction_band_min,
+ contradiction_band_max: state.contradiction_band_max,
data_dir: state.data_dir.clone(),
db_path: state.db_path.clone(),
bind: state.bind.clone(),
diff --git a/crates/ai-memory-mcp/tests/suite/admin_status_search.rs b/crates/ai-memory-mcp/tests/suite/admin_status_search.rs
index 1e258882..618f7eb4 100644
--- a/crates/ai-memory-mcp/tests/suite/admin_status_search.rs
+++ b/crates/ai-memory-mcp/tests/suite/admin_status_search.rs
@@ -28,6 +28,8 @@ async fn make_admin_state(tmp: &TempDir) -> (AdminState, Store) {
embedder: None,
provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path,
bind: "127.0.0.1:49374".to_string(),
diff --git a/crates/ai-memory-mcp/tests/suite/admin_write_page.rs b/crates/ai-memory-mcp/tests/suite/admin_write_page.rs
index ef5c58a9..6a6d2eeb 100644
--- a/crates/ai-memory-mcp/tests/suite/admin_write_page.rs
+++ b/crates/ai-memory-mcp/tests/suite/admin_write_page.rs
@@ -28,6 +28,8 @@ async fn make_state(tmp: &TempDir) -> AdminState {
embedder: None,
provider_health: ai_memory_llm::ProviderHealth::default(),
decay_params: DecayParams::default(),
+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,
+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,
data_dir: tmp.path().to_path_buf(),
db_path,
bind: "127.0.0.1:0".to_string(),
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 1a126017..5ea92480 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -455,7 +455,7 @@ long-lived entry appearing there is that policy working rather than a fault.
| `memory_write_page` | destructive | Write durable wiki knowledge when the user explicitly asks to remember/annotate it. `scope: "global"` writes into the reserved `_global` preferences scope; optional `expires_at` sets an RFC3339 or date-only TTL. |
| `memory_delete_page` | destructive | Delete a single page by exact `path`. Fires the admission chain (op=delete); idempotent. |
| `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 0.4–0.75 cosine-similarity band ("same topic, not a near-duplicate" — ≥0.75 is A3 dedup, <0.4 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. |
+| `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 — raise `contradiction_band_min` (`config.toml` or `AI_MEMORY_CONTRADICTION_BAND_MIN`) for such a store. |
| `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`,
@@ -612,6 +612,16 @@ tcp_keepalive_secs = 60 # idle time before TCP keepalive probes an ac
# (laptop sleep, VPN flap) that would otherwise leak fds
# until EMFILE (#792). 0 disables keepalive. Env:
# AI_MEMORY_TCP_KEEPALIVE_SECS
+contradiction_band_min = 0.4 # `memory_lint`'s A5 zero-LLM contradiction band
+contradiction_band_max = 0.75 # (lower/upper cosine-similarity edge). The band is a
+ # fixed absolute cosine value, but a single-language or
+ # single-domain store's background similarity sits well
+ # above the general-purpose default, so the default band
+ # ends up measuring domain proximity rather than conflict
+ # and produces noisy findings — raise `contradiction_band_min`
+ # for such a store. Must satisfy 0.0 <= min < max <= 1.0.
+ # Env: AI_MEMORY_CONTRADICTION_BAND_MIN /
+ # AI_MEMORY_CONTRADICTION_BAND_MAX
# Capture / launch UX (all default-on where noted). Each has an AI_MEMORY_* env
# override (AI_MEMORY_CAPTURE_ASSISTANT / AI_MEMORY_BACKFILL_ON_START /
diff --git a/docs/cookbook.md b/docs/cookbook.md
index bb342adb..1058d24d 100644
--- a/docs/cookbook.md
+++ b/docs/cookbook.md
@@ -107,7 +107,11 @@ compacted or merged stays in git and the supersession chain, recoverable with
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.
+ candidate pairs: read each finding as a pair to check, not as a defect. 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
+ same-domain-but-unrelated pairs.
- **Let an LLM consolidate on idle ("dream"):** with a provider *and* an embedder
configured, `[dream] enabled` turns on a background pass that rewrites clusters
of cold notes into single coherent pages while you're idle and cancels the