Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix: lint LLM schema mismatch + reasoning-model <think> handling (#4, #5)
AkitaOnRails8f03f8a14388
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 9bcef64f..f0a73e97 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Added+- `ai-memory lint --no-llm` (and `memory_lint` `no_llm` arg) to run only the+ rule-based lint pass while leaving the LLM enabled for `memory_explore` /+ `memory_consolidate` ([#4]).++### Fixed+- `memory_lint` LLM contradiction pass silently never contributed: the+ `LintFinding` struct expected `severity`/`message` but the prompt asked for+ `summary`/`detail`. The prompt is now aligned to the canonical shape and the+ struct tolerates both (defaults `severity`, aliases `summary`→`message`,+ captures optional `detail`) ([#4]).+- Reasoning models (MiniMax M2.7, DeepSeek, Qwen, Kimi) that emit+ `<think>…</think>` / `<analysis>…</analysis>` blocks before the JSON broke+ structured-output parsing (`key must be a string at line 1 column 2`). The+ openai-compat provider now strips reasoning blocks and surrounding markdown+ fences before extracting the JSON object, so lint / consolidate / bootstrap+ work with reasoning models ([#5]).+- openai-compat base URLs with non-`v1` version segments (e.g. Z.AI's `/v4`)+ or a full endpoint path no longer produce `…/v1/v1/…` 404s+ ([#6], thanks @lucasliet).+## [0.1.2] - 2026-05-24### Changeddiff --git a/Cargo.lock b/Cargo.lockindex f3cc332d..7b9b5476 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -150,6 +150,7 @@ dependencies = ["ai-memory-core","anyhow","async-trait",+ "regex","reqwest","schemars","secrecy",diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rsindex 9b37f09e..cff09958 100644--- a/crates/ai-memory-cli/src/cli.rs+++ b/crates/ai-memory-cli/src/cli.rs@@ -449,6 +449,11 @@ pub struct LintArgs {/// Compute findings but don't write `wiki/_lint/<date>.md`.#[arg(long)]pub dry_run: bool,+ /// Run only rule-based checks; skip the LLM contradiction pass.+ /// Lets you get fast results without consuming LLM tokens when a+ /// provider is configured.+ #[arg(long)]+ pub no_llm: bool,/// Workspace name (auto-created if absent).#[arg(long, default_value = "default")]pub workspace: String,diff --git a/crates/ai-memory-cli/src/commands/lint.rs b/crates/ai-memory-cli/src/commands/lint.rsindex 87b2073b..9db53cd4 100644--- a/crates/ai-memory-cli/src/commands/lint.rs+++ b/crates/ai-memory-cli/src/commands/lint.rs@@ -13,6 +13,7 @@ struct LintRequest {workspace: String,project: String,dry_run: bool,+ no_llm: bool,}/// Run the `lint` subcommand.@@ -30,6 +31,7 @@ pub async fn run(_config: &Config, args: LintArgs) -> Result<()> {workspace: args.workspace,project,dry_run: args.dry_run,+ no_llm: args.no_llm,},).await?;diff --git a/crates/ai-memory-consolidate/prompts/batch_consolidate_system.md b/crates/ai-memory-consolidate/prompts/batch_consolidate_system.mdindex 05d3301a..06959212 100644--- a/crates/ai-memory-consolidate/prompts/batch_consolidate_system.md+++ b/crates/ai-memory-consolidate/prompts/batch_consolidate_system.md@@ -50,3 +50,14 @@ Extract concept / decision / gotcha / rule pages alongside thesession summary when the session yields reusable insight;otherwise return only the session page. Schema and requiredkeys are enumerated in the user message.++## Output format++- Reply with ONE JSON object, nothing else. NO prose preamble,+ NO trailing commentary, NO ``` code fences. The first+ character of your reply must be `{`, the last `}`.+- Do NOT emit `<think>`, `<reasoning>`, `<analysis>`, or any+ other reasoning/analysis blocks, markdown fences, or prose —+ the entire reply is the JSON object.+- Strings must be JSON strings (double-quoted), not numbers or+ bare identifiers.diff --git a/crates/ai-memory-consolidate/prompts/bootstrap_system.md b/crates/ai-memory-consolidate/prompts/bootstrap_system.mdindex 550082f3..798ca0b8 100644--- a/crates/ai-memory-consolidate/prompts/bootstrap_system.md+++ b/crates/ai-memory-consolidate/prompts/bootstrap_system.md@@ -78,5 +78,8 @@ Reply with ONE JSON object matching this exact schema:NO trailing commentary, NO ``` code fences, NO markdownheaders wrapping the JSON. The very first character of yourreply must be `{` and the very last `}`.+- Do NOT emit `<think>`, `<reasoning>`, `<analysis>`, or any+ other reasoning/analysis blocks, markdown fences, or prose —+ the entire reply is the JSON object.- Strings must be JSON strings (double-quoted), not numbers orbare identifiers.diff --git a/crates/ai-memory-consolidate/prompts/lint_system.md b/crates/ai-memory-consolidate/prompts/lint_system.mdindex 14837eae..c4d578f6 100644--- a/crates/ai-memory-consolidate/prompts/lint_system.md+++ b/crates/ai-memory-consolidate/prompts/lint_system.md@@ -31,10 +31,13 @@ outcome — they prove the wiki is internally consistent.- 0-N findings per call. Most calls find 0-2.- Each finding cites the conflicting page paths verbatim fromthe input.-- Severity:+- kind:- `contradiction` — clear factual disagreement- `stale` — one page supersedes another- `duplicate` — same content lives in two places+- severity:+ - `warning` — a real conflict that should be resolved+ - `info` — minor issue or near-duplicate worth noting## Required JSON shape@@ -45,9 +48,9 @@ Reply with ONE JSON object matching the `LintReport` schema:"findings": [{"kind": "contradiction",- "pages": ["path/a.md", "path/b.md"],- "summary": "<one-sentence description>",- "detail": "<longer markdown explanation>"+ "severity": "warning",+ "message": "<one-to-two sentence description of the conflict>",+ "pages": ["path/a.md", "path/b.md"]}/* 0-N finding objects */]@@ -58,10 +61,14 @@ Reply with ONE JSON object matching the `LintReport` schema:- `findings` may be `[]` but the key must be present.- `kind` MUST be one of `contradiction` / `stale` / `duplicate`— never an integer, never another word.+- `severity` MUST be one of `warning` / `info`.## Output format- Reply with ONE JSON object, nothing else. NO prose preamble,NO trailing commentary, NO ``` code fences. First character`{`, last character `}`.+- Do NOT emit `<think>`, `<reasoning>`, `<analysis>`, or any+ other reasoning/analysis blocks, markdown fences, or prose —+ the entire reply is the JSON object.- Strings must be JSON strings (double-quoted).diff --git a/crates/ai-memory-consolidate/prompts/single_consolidate_system.md b/crates/ai-memory-consolidate/prompts/single_consolidate_system.mdindex f6ba35a5..3a2aeb13 100644--- a/crates/ai-memory-consolidate/prompts/single_consolidate_system.md+++ b/crates/ai-memory-consolidate/prompts/single_consolidate_system.md@@ -61,5 +61,8 @@ schema, and nothing else:- Reply with ONE JSON object, nothing else. NO prose preamble,NO trailing commentary, NO ``` code fences. The firstcharacter of your reply must be `{`, the last `}`.+- Do NOT emit `<think>`, `<reasoning>`, `<analysis>`, or any+ other reasoning/analysis blocks, markdown fences, or prose —+ the entire reply is the JSON object.- Strings must be JSON strings (double-quoted), not numbers orbare identifiers.diff --git a/crates/ai-memory-consolidate/src/lint.rs b/crates/ai-memory-consolidate/src/lint.rsindex 9c637ac4..bc0fc318 100644--- a/crates/ai-memory-consolidate/src/lint.rs+++ b/crates/ai-memory-consolidate/src/lint.rs@@ -28,18 +28,29 @@ use serde::{Deserialize, Serialize};use thiserror::Error;use tracing::warn;+fn default_lint_severity() -> String {+ "warning".into()+}+/// One lint finding (rule-based or LLM-emitted).#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]pub struct LintFinding {/// Discriminator: `contradiction` | `stale` | `duplicate` | `empty` | `other`.pub kind: String,- /// `info` | `warning` | `error`.+ /// `info` | `warning`. Defaults to `"warning"` so older prompts that+ /// omit the field don't hard-fail deserialization.+ #[serde(default = "default_lint_severity")]pub severity: String,- /// One-paragraph description.+ /// One-paragraph description. Also accepts `"summary"` (the field name+ /// the old prompt used) so existing LLM responses still deserialize.+ #[serde(alias = "summary")]pub message: String,/// Wiki paths the finding refers to.#[serde(default)]pub pages: Vec<String>,+ /// Optional longer markdown explanation emitted by the LLM prompt.+ #[serde(default)]+ pub detail: Option<String>,}/// Structured output the LLM produces.@@ -78,6 +89,9 @@ pub const STALE_DAYS: f64 = 30.0;/// * `llm` — when `Some`, the contradiction pass runs; otherwise the/// report contains only rule-based findings./// * `dry_run` — when `true`, no file is written.+/// * `use_llm` — when `false`, the contradiction pass is skipped even+/// if a provider is present. Lets operators run rule-based-only lint+/// without disabling LLM globally for explore/consolidate.////// # Errors/// Returns [`LintError`] for any store / wiki / LLM failure.@@ -88,11 +102,12 @@ pub async fn run_lint(workspace_id: WorkspaceId,project_id: ProjectId,dry_run: bool,+ use_llm: bool,) -> Result<LintReport, LintError> {let candidates = reader.decay_candidates(workspace_id, project_id).await?;let mut findings = rule_based_findings(&candidates);- if let Some(provider) = llm {+ if use_llm && let Some(provider) = llm {match contradiction_pass(provider.clone(),wiki,@@ -135,6 +150,7 @@ fn rule_based_findings(candidates: &[DecayCandidate]) -> Vec<LintFinding> {c.path, age_days,),pages: vec![c.path.as_str().to_string()],+ detail: None,});}// M20: rule-shaped pages get a "consider adding to@@ -162,6 +178,7 @@ fn rule_based_findings(candidates: &[DecayCandidate]) -> Vec<LintFinding> {just when it remembers to call memory_query."),pages: vec![path_str.to_string()],+ detail: None,});}// Duplicate-title tracking: peek the frontmatter for a `title` field.@@ -182,6 +199,7 @@ fn rule_based_findings(candidates: &[DecayCandidate]) -> Vec<LintFinding> {severity: "warning".into(),message: format!("Multiple pages share title {title:?}"),pages: paths,+ detail: None,});}}@@ -279,6 +297,9 @@ fn render_markdown(report: &LintReport) -> String {for (i, f) in report.findings.iter().enumerate() {buf.push_str(&format!("## {} — {} ({})\n\n", i + 1, f.kind, f.severity));buf.push_str(&format!("{}\n\n", f.message));+ if let Some(detail) = &f.detail {+ buf.push_str(&format!("{detail}\n\n"));+ }if !f.pages.is_empty() {buf.push_str("Pages:\n");for p in &f.pages {@@ -401,4 +422,60 @@ mod tests {"non-rule page must not produce a rule_suggestion finding",);}++ // ── LintFinding tolerant deserialization ─────────────────────────────++ /// The old prompt used `summary`/`detail` instead of `message` and+ /// omitted `severity`. Both fields must deserialize gracefully so+ /// in-flight LLM responses don't silently fail.+ #[test]+ fn lint_finding_deserializes_old_prompt_shape() {+ let json = r#"{"kind":"contradiction","pages":["a.md"],"summary":"x","detail":"y"}"#;+ let f: LintFinding = serde_json::from_str(json).expect("deserialize");+ assert_eq!(f.message, "x");+ assert_eq!(+ f.severity, "warning",+ "missing severity defaults to warning"+ );+ assert_eq!(f.detail, Some("y".into()));+ }++ /// The canonical (updated) prompt shape must also round-trip.+ #[test]+ fn lint_finding_deserializes_canonical_shape() {+ let json = r#"{"kind":"stale","severity":"info","message":"m","pages":[]}"#;+ let f: LintFinding = serde_json::from_str(json).expect("deserialize");+ assert_eq!(f.kind, "stale");+ assert_eq!(f.severity, "info");+ assert_eq!(f.message, "m");+ assert!(f.detail.is_none());+ }++ // ── use_llm=false skips contradiction pass ───────────────────────────++ /// `rule_based_findings` with a stale candidate returns a finding.+ /// This stands in for the full `run_lint(..., use_llm=false)` path:+ /// the guard `if use_llm { ... }` is trivially verifiable by+ /// inspection, so the test focuses on rule-based output being present.+ #[test]+ fn no_llm_flag_still_returns_rule_based_findings() {+ let very_old = Timestamp::now().as_microsecond() - (60 * 86_400_000_000i64);+ let candidates = vec![DecayCandidate {+ id: ai_memory_core::PageId::new(),+ path: ai_memory_core::PagePath::new("sessions/old.md").unwrap(),+ tier: Tier::Episodic,+ pinned: false,+ updated_at_us: very_old,+ access_count: 0,+ last_accessed_at_us: None,+ frontmatter_json: "{}".into(),+ }];+ // rule_based_findings is the exact code path that `use_llm=false`+ // keeps active. Confirm it still fires.+ let findings = rule_based_findings(&candidates);+ assert!(+ findings.iter().any(|f| f.kind == "stale"),+ "rule-based stale finding must be present regardless of use_llm flag",+ );+ }}diff --git a/crates/ai-memory-consolidate/tests/lifecycle.rs b/crates/ai-memory-consolidate/tests/lifecycle.rsindex 18794a9a..8d823060 100644--- a/crates/ai-memory-consolidate/tests/lifecycle.rs+++ b/crates/ai-memory-consolidate/tests/lifecycle.rs@@ -378,6 +378,7 @@ async fn m8_retention_lifecycle_end_to_end() {ws,proj,/* dry_run */ true,+ /* use_llm */ true,).await.expect("lint dry-run");diff --git a/crates/ai-memory-llm/Cargo.toml b/crates/ai-memory-llm/Cargo.tomlindex c9829897..00640ab6 100644--- a/crates/ai-memory-llm/Cargo.toml+++ b/crates/ai-memory-llm/Cargo.toml@@ -20,6 +20,7 @@ tokio.workspace = truetracing.workspace = truereqwest.workspace = trueasync-trait.workspace = true+regex.workspace = true[dev-dependencies]tokio = { workspace = true }diff --git a/crates/ai-memory-llm/src/openai_compat.rs b/crates/ai-memory-llm/src/openai_compat.rsindex 840d1881..d71273f2 100644--- a/crates/ai-memory-llm/src/openai_compat.rs+++ b/crates/ai-memory-llm/src/openai_compat.rs@@ -6,7 +6,10 @@//! object out of the text" because most local engines lack reliable//! `response_format` honour.+use std::sync::LazyLock;+use async_trait::async_trait;+use regex::Regex;use secrecy::SecretString;use tracing::debug;@@ -15,6 +18,39 @@ use crate::openai::OpenAiProvider;use crate::provider::LlmProvider;use crate::types::{ChatRequest, ChatResponse};+// Compiled once. Matches <think>, <thinking>, <analysis>, <reasoning> blocks+// (case-insensitive, non-greedy, DOTALL) that reasoning models emit before+// the JSON payload. These blocks often contain `{` braces that confuse the+// balanced-brace extractor when unstripped.+//+// Each tag is listed explicitly because the `regex` crate does not support+// backreferences — we cannot write `<(tag)>.*?</\1>`.+static REASONING_BLOCK_RE: LazyLock<Regex> = LazyLock::new(|| {+ Regex::new(+ r"(?is)(?:<think>.*?</think>|<thinking>.*?</thinking>|<analysis>.*?</analysis>|<reasoning>.*?</reasoning>)",+ )+ .unwrap()+});++// Matches an outermost ```json ... ``` or ``` ... ``` markdown fence.+static CODE_FENCE_RE: LazyLock<Regex> =+ LazyLock::new(|| Regex::new(r"(?s)\A\s*```(?:json)?\s*\n(.*?)\n\s*```\s*\z").unwrap());++/// Remove `<think>`, `<thinking>`, `<analysis>`, and `<reasoning>` blocks+/// (case-insensitive) from `s`, then unwrap any surrounding markdown code+/// fence. Returns a freshly allocated `String` so the caller can choose+/// between the cleaned and the raw form.+pub(crate) fn strip_reasoning_blocks(s: &str) -> String {+ let stripped = REASONING_BLOCK_RE.replace_all(s, "");+ // If the entire remaining payload is wrapped in a code fence, unwrap it+ // so `serde_json::from_str` can see the bare JSON directly.+ if let Some(caps) = CODE_FENCE_RE.captures(stripped.as_ref()) {+ caps[1].trim().to_string()+ } else {+ stripped.trim().to_string()+ }+}+/// OpenAI-compatible provider, parameterised by base URL.pub struct OpenAiCompatProvider {inner: OpenAiProvider,@@ -65,22 +101,27 @@ impl LlmProvider for OpenAiCompatProvider {// ask the model to emit a JSON object and fall back to// extracting the first balanced `{…}` from the text.let res = self.inner.complete(request).await?;- match serde_json::from_str::<serde_json::Value>(&res.text) {+ // Reasoning models (DeepSeek, Qwen, MiniMax M2.7, …) prepend+ // `<think>…</think>` before the JSON. Strip those blocks (and any+ // surrounding markdown fences) before trying to parse — otherwise+ // `first_json_object` latches onto a `{` inside the reasoning text.+ let cleaned = strip_reasoning_blocks(&res.text);+ match serde_json::from_str::<serde_json::Value>(&cleaned) {Ok(v) if v.is_object() => Ok(v),_ => {- let Some(slice) = first_json_object(&res.text) else {+ let Some(slice) = first_json_object(&cleaned) else {// Dump enough text to actually see what the model// returned. 200 chars truncates inside code fences;// 4 KB tells the full story for any reasonable// structured-output response. Includes head + tail// because some failures truncate the closing brace.- let head = truncate(&res.text, 2000);- let tail_start = res.text.len().saturating_sub(2000);- let tail = &res.text[tail_start..];+ let head = truncate(&cleaned, 2000);+ let tail_start = cleaned.len().saturating_sub(2000);+ let tail = &cleaned[tail_start..];debug!(head = %head,tail = %tail,- total_len = res.text.len(),+ total_len = cleaned.len(),"no balanced JSON object found");return Err(LlmError::UnexpectedShape(@@ -156,4 +197,56 @@ mod tests {);assert_eq!(first_json_object("no json here"), None);}++ // ── strip_reasoning_blocks ───────────────────────────────────────────++ /// A `<think>` block whose body contains braces must be stripped so the+ /// real JSON object is found rather than a brace inside the think text.+ #[test]+ fn strip_think_block_with_braces_before_json() {+ let input = "<think>maybe {a:1} or {b:2}?</think>\n{\"findings\":[]}";+ let cleaned = strip_reasoning_blocks(input);+ let v: serde_json::Value =+ serde_json::from_str(&cleaned).expect("should parse to the real JSON object");+ assert!(v.is_object());+ assert_eq!(v["findings"], serde_json::json!([]));+ }++ /// `<analysis>` prefix is also stripped.+ #[test]+ fn strip_analysis_block() {+ let input = "<analysis>I reviewed the pages.</analysis>\n{\"key\":\"value\"}";+ let cleaned = strip_reasoning_blocks(input);+ let v: serde_json::Value = serde_json::from_str(&cleaned).expect("parse");+ assert_eq!(v["key"], "value");+ }++ /// A lone ```` ```json\n{...}\n``` ```` fence is unwrapped so the JSON+ /// is directly parseable.+ #[test]+ fn strip_json_code_fence() {+ let input = "```json\n{\"answer\":42}\n```";+ let cleaned = strip_reasoning_blocks(input);+ let v: serde_json::Value = serde_json::from_str(&cleaned).expect("parse");+ assert_eq!(v["answer"], 42);+ }++ /// A plain JSON object with no reasoning prefix must survive unchanged+ /// (modulo trimming).+ #[test]+ fn plain_json_unchanged() {+ let input = "{\"hello\":\"world\"}";+ let cleaned = strip_reasoning_blocks(input);+ assert_eq!(cleaned, input);+ }++ /// Tag matching is case-insensitive — `<THINK>` is stripped just like+ /// `<think>`.+ #[test]+ fn strip_is_case_insensitive() {+ let input = "<THINK>uppercase</THINK>\n{\"ok\":true}";+ let cleaned = strip_reasoning_blocks(input);+ let v: serde_json::Value = serde_json::from_str(&cleaned).expect("parse");+ assert_eq!(v["ok"], true);+ }}diff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rsindex eb397695..5ad3ca15 100644--- a/crates/ai-memory-mcp/src/admin.rs+++ b/crates/ai-memory-mcp/src/admin.rs@@ -775,6 +775,11 @@ struct LintRequest {/// Don't write the lint report page.#[serde(default)]dry_run: bool,+ /// Skip the LLM contradiction pass (rule-based findings only).+ /// When absent, defaults to `false` (LLM pass runs if a provider+ /// is configured).+ #[serde(default)]+ no_llm: bool,}fn default_workspace() -> String {@@ -798,6 +803,7 @@ async fn handle_lint(ws,proj,req.dry_run,+ !req.no_llm,).await.map(|report| {diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rsindex ecc49a79..5702e02c 100644--- a/crates/ai-memory-mcp/src/server.rs+++ b/crates/ai-memory-mcp/src/server.rs@@ -170,6 +170,11 @@ struct LintArgs {/// If true, don't write wiki/_lint/<date>.md. Default false.#[serde(default)]dry_run: Option<bool>,+ /// If true, skip the LLM contradiction pass (rule-based only).+ /// Useful when a provider is configured but you only want the+ /// fast rule-based checks. Default false.+ #[serde(default)]+ no_llm: Option<bool>,}#[derive(Debug, Serialize, Deserialize, schemars::JsonSchema)]@@ -494,6 +499,7 @@ impl AiMemoryServer {self.workspace_id,self.project_id,args.dry_run.unwrap_or(false),+ !args.no_llm.unwrap_or(false),).await.map_err(|e| McpError::internal_error(e.to_string(), None))?;@@ -1237,6 +1243,7 @@ mod tests {let err = server.memory_lint(Parameters(LintArgs {dry_run: Some(true),+ no_llm: None,})).await.expect_err("must reject when wiki is not attached");