Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(install-hooks): stop reporting a ZCode config ZCode has rejected as up to date
John Costa8073864692a0
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex fa882713..c9089f09 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -8,6 +8,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]### Fixed+- `install-hooks --agent zcode --apply` no longer reports a hooks block+ ZCode has thrown away as `no-op … (already up to date)` (#600). ZCode+ validates `hooks.events` strictly and rejects the whole block, including+ ai-memory's own entries, over a single key it does not recognize, so+ capture never ran (`hookCount: 0`). Apply only ever merged the six event+ keys it writes, so a key it does not write was neither inspected nor+ reported, the file kept matching byte for byte, and the report claimed+ the install was current. Apply now also withdraws ai-memory's own+ entries from event keys it no longer writes, wherever they sit, and+ reports what it found: a warning naming any key it withdrew from, and a+ note for a key left unable to run anything, both naming the config file.+ **Changed output:** an unchanged ZCode config with such a key now reports+ `no-op … (unchanged; see the notes below)` instead of `already up to+ date`, so a redirected stdout no longer carries the reassurance without+ the cause. Event keys are never deleted and hooks ai-memory did not write+ are never removed, so a key holding someone else's hook is reported, not+ touched.- `as_of` time-travel queries and the entity retrieval stream now workon real stores. Both read the entity index, which was populated onlyfrom an LLM consolidator's `entities:` frontmatter — absent on thediff --git a/crates/ai-memory-cli/src/commands/install_hooks.rs b/crates/ai-memory-cli/src/commands/install_hooks.rsindex 595199ca..f85b7041 100644--- a/crates/ai-memory-cli/src/commands/install_hooks.rs+++ b/crates/ai-memory-cli/src/commands/install_hooks.rs@@ -15,6 +15,7 @@//! and produces no backup.use std::fs;+use std::io::Write;use std::path::{Path, PathBuf};use anyhow::{Context, Result};@@ -4670,13 +4671,75 @@ fn is_our_zcode_hook(hook: &serde_json::Value) -> bool {.is_some_and(|msg| msg.starts_with("ai-memory"))}+/// Withdraw ai-memory's own hook entries from every matcher group in+/// `groups`, leaving each group, and anyone else's hooks inside it, in+/// place.+fn strip_our_zcode_hook_entries(groups: &mut [serde_json::Value]) {+ for group in groups.iter_mut() {+ if let Some(hooks) = group+ .as_object_mut()+ .and_then(|group| group.get_mut("hooks"))+ .and_then(|v| v.as_array_mut())+ {+ hooks.retain(|hook| !is_our_zcode_hook(hook));+ }+ }+}++/// Same, for a `hooks.events` slot of unknown shape. Returns how many+/// entries were withdrawn so the caller can report them; a slot that is+/// not an array is left untouched and counts zero.+fn strip_our_zcode_hooks(slot: &mut serde_json::Value) -> usize {+ let Some(groups) = slot.as_array_mut() else {+ return 0;+ };+ let before = zcode_hook_count(groups);+ strip_our_zcode_hook_entries(groups);+ before.saturating_sub(zcode_hook_count(groups))+}++/// Total hook entries across every matcher group in `groups`, ignoring+/// groups whose `hooks` is absent or not an array.+fn zcode_hook_count(groups: &[serde_json::Value]) -> usize {+ groups+ .iter()+ .filter_map(|group| group.get("hooks").and_then(|v| v.as_array()))+ .map(|hooks| hooks.len())+ .sum()+}++/// True when a `hooks.events` entry cannot run anything: no matcher groups+/// at all, no group carrying a non-empty `hooks` array, or a value that is+/// not a matcher-group array in the first place. Such a key is pure+/// downside under ZCode's strict validation, since it runs nothing and can+/// cost the user every other hook in the block.+///+/// Deliberately narrower than "a key ai-memory does not write": several of+/// those are real ZCode events this tool skips on purpose (see+/// `PermissionRequest` in `render_shared`), and a key still running+/// someone's hook is their working config, not a leftover. Reporting on+/// that set would be a false-positive generator.+fn zcode_event_runs_nothing(slot: &serde_json::Value) -> bool {+ match slot.as_array() {+ Some(groups) => zcode_hook_count(groups) == 0,+ None => true,+ }+}+/// Merge ai-memory hooks into the root `hooks` block of ZCode's/// user-scope `~/.zcode/cli/config.json` (#512). Sibling config keys/// (`model`, `provider`, `mcp.servers`, …) always survive: the merge/// touches only `hooks.enabled` (defaulted, never flipped),/// `hooks.maxOutputBytes` (set only when absent), and `hooks.events`,/// replaces entries ai-memory owns (idempotent re-apply), and never-/// edits matcher groups it did not write.+/// removes a hook it did not write. Entries it owns are withdrawn+/// wherever they sit, including under event keys this version no longer+/// writes; event keys themselves are never deleted, only reported when+/// ai-memory withdrew entries from them, or when they are left unable to+/// run anything (#600). The one thing it does+/// discard is a matcher group left holding an empty `hooks` array under a+/// key it writes, which drops a caller's own empty group along with the+/// ones its withdrawal emptied.fn apply_to_zcode_hooks(server_url: &str,auth_token: Option<&str>,@@ -4700,6 +4763,7 @@ fn apply_to_zcode_hooks(.context("internal: build_zcode_hooks_config didn't return an events map")?.clone();let mut hooks_disabled = false;+ let mut stale: Vec<(String, usize, bool)> = Vec::new();let outcome = apply_atomic(&path, |existing| {mutate_json(existing, |root| {// `hooks` sits beside sibling config keys that must survive.@@ -4736,21 +4800,33 @@ fn apply_to_zcode_hooks(let slot = slot.as_array_mut().context("`hooks.events.{event}` is present in the ZCode config but not an array",)?;- for group in slot.iter_mut() {- if let Some(hooks) = group- .as_object_mut()- .and_then(|group| group.get_mut("hooks"))- .and_then(|v| v.as_array_mut())- {- hooks.retain(|hook| !is_our_zcode_hook(hook));- }- }+ strip_our_zcode_hook_entries(slot);slot.retain(|group| match group.get("hooks") {Some(serde_json::Value::Array(hooks)) => !hooks.is_empty(),_ => true,});slot.extend(ours.iter().cloned());}+ // ai-memory writes only the six keys in `ZCODE_EVENTS`, but its+ // own entries can sit under other keys too (a config carried+ // over from another agent, or hand-edited). Those are ours to+ // withdraw; the keys themselves are not, so every one is left+ // in place. What makes a leftover dangerous is ZCode strict-+ // validating this map: one key it does not recognize and it+ // rejects the ENTIRE hooks block, ai-memory's included, so+ // capture dies while the file still matches byte for byte and+ // apply reports it as up to date (#600). Collect the keys that+ // can no longer run anything and say so after the write.+ for (event, slot) in events.iter_mut() {+ if our_events.contains_key(event) {+ continue;+ }+ let withdrawn = strip_our_zcode_hooks(slot);+ let runs_nothing = zcode_event_runs_nothing(slot);+ if withdrawn > 0 || runs_nothing {+ stale.push((event.clone(), withdrawn, runs_nothing));+ }+ }Ok(())})})?;@@ -4761,7 +4837,13 @@ fn apply_to_zcode_hooks(match outcome {ApplyOutcome::Created => "new file",ApplyOutcome::Updated => "backup written next to it",- ApplyOutcome::NoOp => "already up to date",+ // Only claim the install is current when nothing turned up+ // that can stop ZCode loading it. Saying "already up to date"+ // over a block ZCode rejects is the whole of #600, and the+ // notes explaining it go to stderr, so a redirected stdout+ // would otherwise carry the reassurance and none of the cause.+ ApplyOutcome::NoOp if stale.is_empty() => "already up to date",+ ApplyOutcome::NoOp => "unchanged; see the notes below",});if hooks_disabled {@@ -4771,6 +4853,42 @@ fn apply_to_zcode_hooks(you re-enable them.");}+ if !stale.is_empty() {+ // The report above goes to stdout and these go to stderr; stdout+ // block-buffers when redirected, so without this the two arrive out+ // of order in a log or in CI.+ let _ = std::io::stdout().flush();+ }+ for (event, withdrawn, runs_nothing) in &stale {+ if *withdrawn > 0 {+ // A withdrawal is positive evidence ai-memory once lived under+ // this key, so the risk here is not hypothetical.+ eprintln!(+ "# warning: withdrew {withdrawn} ai-memory hook(s) from \+ `hooks.events.{event}`, a key ai-memory does not write. The \+ key itself was left as found, but ZCode validates this map \+ strictly and rejects the ENTIRE hooks block, ai-memory's \+ included, over one key it does not recognize, which leaves \+ capture silently dead. If ZCode reports `hookCount: 0`, \+ remove that key from {}.",+ path.display()+ );+ } else if *runs_nothing {+ eprintln!(+ // Only the provenance claim degrades between the two+ // tiers; the consequence is identical, so state it at full+ // strength. "If ZCode does not recognize it" keeps this+ // honest about keys ZCode does accept, such as an empty+ // `Notification`.+ "# note: `hooks.events.{event}` runs nothing, and ai-memory \+ does not write that key. If ZCode does not recognize it, \+ ZCode rejects the ENTIRE hooks block, ai-memory's included, \+ and capture is dead while this file looks correct. If ZCode \+ reports `hookCount: 0`, remove that key from {}.",+ path.display()+ );+ }+ }println!("# NOTE: ZCode injects SessionStart stdout as model context, so the");println!("# prior session's handoff is delivered automatically.");println!("# NOTE: ZCode fires `Stop` at the end of every turn and has no");@@ -6408,6 +6526,119 @@ command = "AI_MEMORY_HOOK_URL=http://h AI_MEMORY_PROJECT_STRATEGY=repo-root /x/a}}+ #[test]+ fn zcode_apply_withdraws_our_hooks_from_foreign_keys_and_keeps_the_rest() {+ let tmp = TempDir::new().unwrap();+ let path = tmp.path().join("config.json");+ // Keys outside `ZCODE_EVENTS`. ZCode rejects the whole block over+ // ones it does not recognize, which is how #600 stayed invisible.+ // `SessionEnd` runs nothing, `PreCompact` holds only our entry, and+ // `Notification` mixes our entry with a hook we did not write.+ fs::write(+ &path,+ r#"{+ "hooks": {+ "enabled": true,+ "events": {+ "SessionEnd": [],+ "PreCompact": [+ {"hooks": [+ {"type": "process", "command": "/old/ai-memory", "args": [],+ "enabled": true, "statusMessage": "ai-memory capture"}+ ]}+ ],+ "Notification": [+ {"hooks": [+ {"type": "process", "command": "/old/ai-memory", "args": [],+ "enabled": true, "statusMessage": "ai-memory capture"},+ {"type": "process", "command": "/usr/bin/true", "args": [], "enabled": true}+ ]}+ ]+ }+ }+}"#,+ )+ .unwrap();+ let args = InstallHooksArgs {+ agent: AgentChoice::Zcode,+ capture_assistant: false,+ config_file: Some(path.clone()),+ ..default_hook_args()+ };++ apply_to_zcode_hooks(+ "http://127.0.0.1:49374",+ Some("tok-test"),+ Path::new("/data"),+ &args,+ )+ .unwrap();++ let first = fs::read_to_string(&path).unwrap();+ let root: serde_json::Value = serde_json::from_str(&first).unwrap();+ let events = root["hooks"]["events"].as_object().unwrap();++ // Event keys are never deleted: they are not ai-memory's to remove.+ assert!(events.contains_key("SessionEnd"));+ assert!(events.contains_key("PreCompact"));+ // Our own stale entry is withdrawn wherever it sits.+ assert_eq!(+ events["PreCompact"][0]["hooks"].as_array().unwrap().len(),+ 0,+ "our entry under a key we no longer write must be withdrawn"+ );+ // The mixed group is the only case where the ownership filter+ // decides anything: the foreign hook survives, ours does not.+ let notification = events["Notification"][0]["hooks"].as_array().unwrap();+ assert_eq!(notification.len(), 1, "the hook we did not write must stay");+ assert_eq!(+ notification[0]["command"],+ serde_json::json!("/usr/bin/true")+ );+ for (zcode_event, _) in super::super::render_shared::ZCODE_EVENTS {+ assert!(+ root["hooks"]["events"][zcode_event].is_array(),+ "missing {zcode_event}"+ );+ }++ // Re-apply is still a no-op once the withdrawal has happened.+ apply_to_zcode_hooks(+ "http://127.0.0.1:49374",+ Some("tok-test"),+ Path::new("/data"),+ &args,+ )+ .unwrap();+ assert_eq!(first, fs::read_to_string(&path).unwrap());+ }++ #[test]+ fn zcode_event_runs_nothing_covers_degenerate_matcher_groups() {+ // Each of these leaves the key present but unable to run anything,+ // which is what makes ZCode reject the block while the file still+ // looks settled (#600).+ for shape in [+ serde_json::json!([]),+ serde_json::json!([{}]),+ serde_json::json!([{"matcher": "*"}]),+ serde_json::json!([{"hooks": []}]),+ serde_json::json!([{"hooks": null}]),+ ] {+ assert!(+ zcode_event_runs_nothing(&shape),+ "expected {shape} to run nothing"+ );+ }+ assert!(!zcode_event_runs_nothing(&serde_json::json!([+ {"hooks": [{"type": "process", "command": "/usr/bin/true"}]}+ ])));+ // A value that is not a matcher-group array cannot run hooks either,+ // and is doubly invalid to ZCode. It is left unmodified, but it is+ // still reported: staying quiet about it is the #600 failure.+ assert!(zcode_event_runs_nothing(&serde_json::json!(42)));+ }+#[test]fn zcode_apply_flags_a_user_disabled_hooks_block() {let tmp = TempDir::new().unwrap();