Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
doctor: fix repo-root keying, status mapping, and script-hook caveat
Maxsuel Einsteinf7a569ea412d
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 713fbf80..4efa7b4a 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Added+- `ai-memory doctor` now reports Claude Code's native `memory/` store for+ the current checkout (location, file count, and whether the nearest+ marker's `ignore_paths` would exclude a read of it), so an operator can+ see whether the harness's own auto-memory is being captured without+ reading it themselves (harness-issue #1003). Resolved by repository root,+ so a worktree or a subdirectory reports the same store as the main+ checkout. Shell/PowerShell hook installs (the Docker-wrapper default) do+ not enforce this exclusion at all; the report says so.+### Fixed- `ai-memory doctor` now warns when the nearest `.ai-memory.toml`'s`[capture]` section is invalid. This fails closed today — every file anddiff --git a/crates/ai-memory-cli/src/commands/doctor.rs b/crates/ai-memory-cli/src/commands/doctor.rsindex 139c0136..627aa13e 100644--- a/crates/ai-memory-cli/src/commands/doctor.rs+++ b/crates/ai-memory-cli/src/commands/doctor.rs@@ -27,7 +27,10 @@ use anyhow::{Context, Result};use serde::{Deserialize, Serialize};use ai_memory_core::AgentKind;-use ai_memory_workstream::{ManagedHarness, build_launch_plan, list_native_sessions};+use ai_memory_hooks::CaptureDisposition;+use ai_memory_workstream::{+ ManagedHarness, build_launch_plan, list_native_sessions, native_memory_dir,+};use crate::config::Config;use crate::http_client::{ServerEndpoint, get_json};@@ -122,6 +125,11 @@ struct DoctorReport {/// with no other signal anywhere that the marker stopped working as/// configured, so `doctor` is the one place that surfaces it.marker_capture_problem: Option<MarkerCaptureProblem>,+ /// Native "memory" stores found for harnesses that keep one, and whether+ /// the nearest marker would exclude a read of them (harness-issue+ /// #1003). Only Claude Code's location is known today; harnesses with no+ /// established convention are simply absent from this list.+ native_memory: Vec<NativeMemoryReport>,}#[derive(Debug, Clone, Serialize)]@@ -130,6 +138,20 @@ struct MarkerCaptureProblem {reason: String,}+#[derive(Debug, Clone, Serialize)]+struct NativeMemoryReport {+ agent: String,+ path: String,+ file_count: usize,+ /// One of `"excluded"`, `"not excluded"`, `"marker invalid"`, or+ /// `"metadata only"` (an active, valid policy whose extraction for this+ /// specific probe fell back to the metadata-only disposition — kept+ /// distinct from `"not excluded"` rather than folded into it, since the+ /// two mean different things: the dispositions are mapped one-to-one,+ /// never collapsed).+ status: String,+}+/// Fold the raw per-harness local scans and the server's captured counts into/// one row per agent kind. Pure: no IO, so the verdict logic is unit-tested/// directly. Rows for agent kinds that neither ran locally nor captured@@ -200,6 +222,82 @@ pub(crate) fn relocated_session_dir(harness: ManagedHarness) -> Option<PathBuf>.and_then(|plan| plan.session_dir)}+/// Harnesses whose native "memory" store location is known, so `doctor` can+/// report on it (harness-issue #1003). Only Claude Code's is established+/// today — `~/.claude/projects/<project>/memory/`, found via+/// [`native_memory_dir`]'s content-based match rather than a guessed,+/// platform-specific directory name. A harness left out of this list simply+/// produces no report line, which is the documented behavior for "location+/// unknown" rather than an error.+const HARNESSES_WITH_KNOWN_NATIVE_MEMORY: &[ManagedHarness] = &[ManagedHarness::Claude];++/// For every harness in [`HARNESSES_WITH_KNOWN_NATIVE_MEMORY`] that actually+/// has a memory store for this checkout, report its location, how many+/// files it holds, and whether the nearest marker would exclude a read of+/// it.+///+/// `cwd` is resolved to the repository root first (worktrees and+/// subdirectories collapse onto it): Claude Code keys its auto-memory by+/// repository root, so [`native_memory_dir`] -- which only matches a session+/// recorded for the exact cwd it is given -- would otherwise find nothing+/// when `doctor` runs from a subdirectory or a linked worktree.+///+/// The exclusion check reuses two already-verified read-only facts rather+/// than re-deriving anything: [`super::hook_capture::capture_config_problem`]+/// (a broken marker is reported as `"marker invalid"`, the same diagnosis+/// `doctor`'s other check makes) and, when the marker parses and compiles,+/// [`ai_memory_hooks::CapturePolicy::inspect`] on a synthetic read of one+/// file inside the store — the exact evaluation the native hook performs on+/// a real `Read` tool call, just never sent anywhere. Every+/// `CaptureDisposition` maps to its own distinct status string; none are+/// folded together.+fn native_memory_reports(home: &Path, cwd: &Path) -> Vec<NativeMemoryReport> {+ let repo_root =+ ai_memory_consolidate::discover_main_repo_root(cwd).unwrap_or_else(|_| cwd.to_path_buf());+ let Some(repo_root_str) = repo_root.to_str() else {+ return Vec::new();+ };+ let mut reports = Vec::new();+ for &harness in HARNESSES_WITH_KNOWN_NATIVE_MEMORY {+ let session_dir = relocated_session_dir(harness);+ let Some(memory_dir) = native_memory_dir(harness, home, &repo_root, session_dir.as_deref())+ else {+ continue;+ };+ let file_count = std::fs::read_dir(&memory_dir)+ .map(|entries| {+ entries+ .filter_map(Result::ok)+ .filter(|entry| entry.file_type().is_ok_and(|ft| ft.is_file()))+ .count()+ })+ .unwrap_or(0);+ let status = if super::hook_capture::capture_config_problem(repo_root_str).is_some() {+ "marker invalid"+ } else {+ let policy = super::hook_capture::capture_policy(repo_root_str);+ let probe_path = memory_dir.join("probe.md");+ let raw = serde_json::json!({+ "tool_name": "Read",+ "tool_input": { "file_path": probe_path.to_string_lossy() },+ });+ let decision = policy.inspect(harness.agent_kind(), &raw, repo_root_str);+ match decision.protocol().disposition() {+ CaptureDisposition::Drop => "excluded",+ CaptureDisposition::Keep => "not excluded",+ CaptureDisposition::MetadataOnly => "metadata only",+ }+ };+ reports.push(NativeMemoryReport {+ agent: harness.agent_kind().as_str().to_owned(),+ path: memory_dir.display().to_string(),+ file_count,+ status: status.to_owned(),+ });+ }+ reports+}+/// [`scan_local`] with the relocation lookup passed in. The lookup reads the/// process environment, so a test that plants a fixture under a temporary/// `$HOME` passes `|_| None`: otherwise a developer's `CLAUDE_CONFIG_DIR`@@ -311,6 +409,8 @@ pub async fn run(config: &Config, args: crate::cli::DoctorArgs) -> Result<()> {})});+ let native_memory = native_memory_reports(&home, &cwd);+let report = DoctorReport {workspace,project,@@ -319,6 +419,7 @@ pub async fn run(config: &Config, args: crate::cli::DoctorArgs) -> Result<()> {rows,uncaptured,marker_capture_problem,+ native_memory,};if args.json {@@ -350,6 +451,15 @@ fn render_human(report: &DoctorReport) {);}+ if !report.native_memory.is_empty() {+ println!(+ "Note: a shell/PowerShell hook install (the Docker-wrapper default) does not \+ enforce capture-policy v1 — \"excluded\" below only holds on a native hook \+ install or a generated integration. Run `ai-memory install-hooks` to check which \+ one is active.\n"+ );+ }+if report.rows.is_empty() {println!(" No local harness sessions found for this project and nothing captured yet.");return;@@ -368,6 +478,15 @@ fn render_human(report: &DoctorReport) {row.agent);}+ if let Some(memory) = report.native_memory.iter().find(|m| m.agent == row.agent) {+ println!(+ " native memory: {} ({} file{})",+ memory.path,+ memory.file_count,+ if memory.file_count == 1 { "" } else { "s" }+ );+ println!(" capture: {}", memory.status);+ }}if report.uncaptured.is_empty() {@@ -543,4 +662,135 @@ mod tests {let none = scan_local_with(empty_home.path(), cwd.path(), 0, |_| None).await;assert!(none.is_empty(), "no stores should mean no scans: {none:?}");}++ /// Plants a Claude Code session (for `cwd`) with a sibling `memory/`+ /// directory under `home`, the fixture every `native_memory_reports`+ /// test below starts from.+ fn claude_memory_fixture(home: &Path, cwd: &Path) -> PathBuf {+ let project_dir = home.join(".claude/projects/fixture");+ std::fs::create_dir_all(&project_dir).unwrap();+ std::fs::write(+ project_dir.join("session.jsonl"),+ format!(+ "{}\n",+ serde_json::json!({+ "sessionId": "11111111-2222-3333-4444-555555555555",+ "cwd": cwd.to_string_lossy(),+ })+ ),+ )+ .unwrap();+ let memory_dir = project_dir.join("memory");+ std::fs::create_dir_all(&memory_dir).unwrap();+ memory_dir+ }++ fn find_claude_report(reports: &[NativeMemoryReport]) -> &NativeMemoryReport {+ reports+ .iter()+ .find(|r| r.agent == "claude-code")+ .unwrap_or_else(|| panic!("expected a claude-code report; got {reports:?}"))+ }++ #[test]+ fn native_memory_reports_is_not_excluded_without_a_marker() {+ let home = tempfile::tempdir().unwrap();+ let cwd = tempfile::tempdir().unwrap();+ let memory_dir = claude_memory_fixture(home.path(), cwd.path());+ std::fs::write(memory_dir.join("fact.md"), "x").unwrap();++ let reports = native_memory_reports(home.path(), cwd.path());+ let claude = find_claude_report(&reports);+ assert_eq!(claude.status, "not excluded");+ assert_eq!(claude.file_count, 1);+ }++ #[test]+ fn native_memory_reports_is_excluded_when_the_marker_covers_it() {+ let home = tempfile::tempdir().unwrap();+ let cwd = tempfile::tempdir().unwrap();+ let memory_dir = claude_memory_fixture(home.path(), cwd.path());+ std::fs::write(memory_dir.join("fact.md"), "x").unwrap();+ // An absolute pattern naming the fixture's own (fake) home, so this+ // does not depend on the real process `$HOME` the way a `~/...`+ // pattern would inside capture_policy's own home resolution.+ std::fs::write(+ cwd.path().join(".ai-memory.toml"),+ format!(+ "[capture]\nignore_paths = [{:?}]\n",+ format!("{}/.claude/projects/**", home.path().display())+ ),+ )+ .unwrap();++ let reports = native_memory_reports(home.path(), cwd.path());+ let claude = find_claude_report(&reports);+ assert_eq!(claude.status, "excluded");+ }++ #[test]+ fn native_memory_reports_is_marker_invalid_for_a_broken_capture_table() {+ let home = tempfile::tempdir().unwrap();+ let cwd = tempfile::tempdir().unwrap();+ claude_memory_fixture(home.path(), cwd.path());+ // The exact dropped-`#` shape found in practice: a stray token right+ // after a `[capture]` header.+ std::fs::write(+ cwd.path().join(".ai-memory.toml"),+ "[capture] this used to be a comment\nignore_paths = [\"**\"]\n",+ )+ .unwrap();++ let reports = native_memory_reports(home.path(), cwd.path());+ let claude = find_claude_report(&reports);+ assert_eq!(claude.status, "marker invalid");+ }++ #[test]+ fn native_memory_reports_file_count_ignores_subdirectories() {+ let home = tempfile::tempdir().unwrap();+ let cwd = tempfile::tempdir().unwrap();+ let memory_dir = claude_memory_fixture(home.path(), cwd.path());+ std::fs::write(memory_dir.join("fact.md"), "x").unwrap();+ std::fs::create_dir_all(memory_dir.join("a-subdirectory")).unwrap();+ std::fs::write(memory_dir.join("a-subdirectory/nested.md"), "y").unwrap();++ let reports = native_memory_reports(home.path(), cwd.path());+ let claude = find_claude_report(&reports);+ assert_eq!(+ claude.file_count, 1,+ "the subdirectory itself must not be counted as a file"+ );+ }++ /// The bug found in review: Claude Code keys its auto-memory by+ /// repository root, so running `doctor` from a subdirectory (or a linked+ /// worktree) must still resolve the root's `memory/` store, not come up+ /// empty because the session was recorded for the root and not the+ /// subdirectory `doctor` happened to run from.+ #[test]+ fn native_memory_reports_resolves_a_subdirectory_to_the_repository_root() {+ let home = tempfile::tempdir().unwrap();+ let repo = tempfile::tempdir().unwrap();+ let status = std::process::Command::new("git")+ .args(["init", "-q"])+ .arg(repo.path())+ .status();+ if !matches!(status, Ok(s) if s.success()) {+ // No git binary in this environment: the repo-root resolution+ // falls back to the given cwd unchanged, so there is nothing+ // this test can distinguish here. Skip rather than fail.+ return;+ }+ let subdir = repo.path().join("sub/dir");+ std::fs::create_dir_all(&subdir).unwrap();+ // The session was recorded for the repository ROOT, as Claude Code+ // itself would record it -- not for the subdirectory.+ let memory_dir = claude_memory_fixture(home.path(), repo.path());+ std::fs::write(memory_dir.join("fact.md"), "x").unwrap();++ let reports = native_memory_reports(home.path(), &subdir);+ let claude = find_claude_report(&reports);+ assert_eq!(claude.file_count, 1);+ }}diff --git a/crates/ai-memory-workstream/src/lib.rs b/crates/ai-memory-workstream/src/lib.rsindex 32b804ff..ae6a13c1 100644--- a/crates/ai-memory-workstream/src/lib.rs+++ b/crates/ai-memory-workstream/src/lib.rs@@ -24,6 +24,6 @@ pub use repository::{RepositoryIdentity, inspect_repository};pub use transcript::{AmbiguousNativeSession, ExportedTranscript, NativeSessionCandidate, discover_native_session,export_transcript, kiro_harness_from_source_cursor, kiro_v3_resume_uses_default_store,- list_native_sessions, native_session_exists, native_session_in_checkout,+ list_native_sessions, native_memory_dir, native_session_exists, native_session_in_checkout,wait_for_transcript_flush,};diff --git a/crates/ai-memory-workstream/src/transcript.rs b/crates/ai-memory-workstream/src/transcript.rsindex 498a3d0d..6a897868 100644--- a/crates/ai-memory-workstream/src/transcript.rs+++ b/crates/ai-memory-workstream/src/transcript.rs@@ -266,6 +266,60 @@ pub async fn list_native_sessions(Ok(sessions)}+/// Resolve the on-disk directory holding this harness's native "memory"+/// store for the given checkout, when the harness has one and a session+/// recorded for this cwd can be found.+///+/// Claude Code keeps a `memory/` directory as a sibling of its own session+/// transcripts, at `<home>/.claude/projects/<project-dir>/memory/` — the+/// native store `ai-memory doctor` warns about capturing unless a marker's+/// `ignore_paths` excludes it (harness-issue #1003). `<project-dir>`'s name+/// is Claude Code's own encoding of the cwd, which is **not** the same+/// encoding on every platform (native Windows also folds `\` and `:`, not+/// only `/`), so this never re-derives that name. Instead it reuses the same+/// content-based match [`list_native_sessions`] uses — read each session+/// file's own recorded `cwd` until one matches — and returns that file's+/// parent directory, which is correct on any platform by construction.+///+/// Callers should pass the checkout's **repository root**, not an arbitrary+/// subdirectory: Claude Code keys this store by repository root, so a+/// worktree or a subdirectory shares the root's `memory/` directory. This+/// function itself does no such resolution -- it matches whatever `cwd` it+/// is given against recorded session cwds -- so passing a subdirectory here+/// finds nothing even when a `memory/` store genuinely exists for the+/// repository.+///+/// Harnesses with no known native-memory convention return `None`+/// unconditionally; callers should treat that as "nothing to report", not as+/// an error.+#[must_use]+pub fn native_memory_dir(+ harness: ManagedHarness,+ home: &Path,+ cwd: &Path,+ session_dir: Option<&Path>,+) -> Option<PathBuf> {+ if harness != ManagedHarness::Claude {+ return None;+ }+ let mut files = collect_session_files(harness, home, session_dir).ok()?;+ files.sort_by(|left, right| {+ modified(right)+ .cmp(&modified(left))+ .then_with(|| left.cmp(right))+ });+ for path in files {+ let Ok(Some((_, recorded_cwd))) = session_header_for_cwd(harness, &path, cwd) else {+ continue;+ };+ if same_path(&recorded_cwd, cwd) {+ let memory_dir = path.parent()?.join("memory");+ return memory_dir.is_dir().then_some(memory_dir);+ }+ }+ None+}+/// Whether the native store holds `native_session_id` for this checkout./// [`native_session_exists`] answers for the store; OpenCode keeps every/// checkout's sessions in one database, so there the recorded directory must@@ -5938,4 +5992,89 @@ mod tests {// A ten-byte varint may carry only one payload bit in its final byte.assert_eq!(protobuf_varint(&[0xff; 10]), None);}++ #[test]+ fn native_memory_dir_finds_the_sibling_memory_directory_for_claude() {+ let temp = tempfile::tempdir().unwrap();+ let home = temp.path().join("home");+ let cwd = temp.path().join("repo");+ fs::create_dir_all(&cwd).unwrap();+ // Claude Code's own project-directory name is irrelevant here -- the+ // whole point of this function is to find it by content, never by+ // guessing the encoding (which differs between POSIX and native+ // Windows).+ let project_dir = home.join(".claude/projects/some-encoded-name");+ fs::create_dir_all(&project_dir).unwrap();+ fs::write(+ project_dir.join("session-1.jsonl"),+ format!("{}\n", json!({"sessionId": "abc", "cwd": cwd})),+ )+ .unwrap();+ let memory_dir = project_dir.join("memory");+ fs::create_dir_all(&memory_dir).unwrap();+ fs::write(memory_dir.join("fact.md"), "hello").unwrap();++ assert_eq!(+ native_memory_dir(ManagedHarness::Claude, &home, &cwd, None),+ Some(memory_dir)+ );+ }++ #[test]+ fn native_memory_dir_is_none_without_a_memory_subdirectory() {+ let temp = tempfile::tempdir().unwrap();+ let home = temp.path().join("home");+ let cwd = temp.path().join("repo");+ fs::create_dir_all(&cwd).unwrap();+ let project_dir = home.join(".claude/projects/some-encoded-name");+ fs::create_dir_all(&project_dir).unwrap();+ fs::write(+ project_dir.join("session-1.jsonl"),+ format!("{}\n", json!({"sessionId": "abc", "cwd": cwd})),+ )+ .unwrap();++ // A real session was found, but it never created a memory/ store.+ assert_eq!(+ native_memory_dir(ManagedHarness::Claude, &home, &cwd, None),+ None+ );+ }++ #[test]+ fn native_memory_dir_is_none_when_no_session_matches_this_cwd() {+ let temp = tempfile::tempdir().unwrap();+ let home = temp.path().join("home");+ let cwd = temp.path().join("repo");+ let other = temp.path().join("other");+ fs::create_dir_all(&cwd).unwrap();+ let project_dir = home.join(".claude/projects/some-encoded-name");+ fs::create_dir_all(&project_dir).unwrap();+ fs::write(+ project_dir.join("session-1.jsonl"),+ format!("{}\n", json!({"sessionId": "abc", "cwd": other})),+ )+ .unwrap();+ fs::create_dir_all(project_dir.join("memory")).unwrap();++ assert_eq!(+ native_memory_dir(ManagedHarness::Claude, &home, &cwd, None),+ None+ );+ }++ #[test]+ fn native_memory_dir_is_none_for_harnesses_with_no_known_convention() {+ let temp = tempfile::tempdir().unwrap();+ let home = temp.path().join("home");+ let cwd = temp.path().join("repo");+ fs::create_dir_all(&cwd).unwrap();++ // Codex has no established native-memory convention today, so this+ // must return None unconditionally rather than guess at a location.+ assert_eq!(+ native_memory_dir(ManagedHarness::Codex, &home, &cwd, None),+ None+ );+ }}