Skip to content

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

Rust

docs(instructions): resync AGENTS.md with the slim routing snippet + guard drift

Djalma Júniorc7a7dc290de4
diff --git a/AGENTS.md b/AGENTS.md
index 812fb12c..8efcea09 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,135 +4,66 @@
This project uses [ai-memory](https://github.com/akitaonrails/ai-memory)
for cross-session continuity.
-**Default to the current project — always.** Every ai-memory tool
+**Default to the current project - always.** Every ai-memory tool
auto-scopes to the project resolved from your session's working
-directory. **Do NOT pass `project`, `workspace`, or `cwd` arguments unless the user
-explicitly references a *different* project by name** (e.g. "what did we
-decide in the `other-app` project?"). Phrases like "this project",
-"here", "we", "our work", "where did we leave off" all mean the *current*
-project — call the tool with no scoping args. If the user asks about a
-handoff and the SessionStart auto-fetched block is already in your
-context, just answer from it; do not re-call the tool to "find it again"
-in another project.
-
-**Lifecycle hooks already capture every prompt + tool call
-automatically.** You never need to manually write routine notes; the
-SessionStart hook auto-fetches pending handoffs, and on session end
-ai-memory writes a session-summary page and a handoff.
-LLM consolidation (compiling observations into topical wiki pages) runs
-on PreCompact, on demand via `memory_consolidate`, and at session end
-only when the server sets `AI_MEMORY_CONSOLIDATE_ON_SESSION_END`. Only
-write a durable wiki page when the user explicitly asks to remember or
-annotate something permanently.
-
-### When to reach for each tool
-
-The user can express any of the intents below in plain English —
-match the intent to the tool. They do not need to name the tool.
-
-| User says / situation | Tool |
-|---|---|
-| "have we discussed X?" / "search memory for Y" / before proposing architecture | `memory_query` (current project; `scopes` for named siblings; `global=true` to search every project) |
-| "what's been going on" / "show recent activity" (light) | `memory_recent` |
-| "is ai-memory healthy?" / "how big is the wiki?" | `memory_status` |
-| "give me the stats" / structured snapshot for the agent to consume | `memory_briefing` (read-only; never creates handoffs) |
-| "catch me up" / "I've been away" / "what's important right now?" / open-ended exploration | `memory_explore` |
-| "where did we leave off?" — and you see a `📥 ai-memory: pending handoff` block in your context | already done — answer from that block; do NOT re-call `memory_handoff_accept` |
-| "where did we leave off?" — and no such block is visible | `memory_handoff_accept` (rare; the SessionStart hook usually got there first; pass `workspace` + `project` together only for a named sibling workspace/project) |
-| "save context for the next session" / wrapping up / ending this session | `memory_handoff_begin` (session-end only; do **not** use for status/briefing; single-use handoff; terse summary; put detail in `open_questions` + `next_steps` bullets; pass `workspace` + `project` together only for a named sibling workspace/project) |
-| "discard that handoff" / "I created a handoff by mistake" | `memory_handoff_cancel` (requires exact `handoff_id` from `memory_handoff_begin`; marks it expired before the next session sees it) |
-| "consolidate this session" / "compile what we learned" (also runs on PreCompact; at session end only if `AI_MEMORY_CONSOLIDATE_ON_SESSION_END` is set) | `memory_consolidate` |
-| "what did we learn from this session?" / "what memory should we add?" / explicit wrap-up learning review | `memory_auto_improve` (manual learning review for a completed session; omit `session_id` for latest completed session; the server also schedules background review for newly completed sessions in every project when configured) |
-| "remember this permanently" / "save a note" / "add an annotation" / durable project knowledge | `memory_write_page` (write a wiki page; do **not** use handoff for permanent notes; put the title as a `# H1` on the first line of `body` and omit the `title` arg — ai-memory derives it from the H1) |
-| "read the page about X" / "show me the full content of Y" / "open the page on Z" | `memory_read_page` (full body; pass a query to search or `path` for a direct lookup; pass `workspace` + `project` together only for a named sibling workspace/project) |
-| "delete the page X" / "remove that note" | `memory_delete_page` (by exact `path`; idempotent; pass `workspace` + `project` together only for a named sibling workspace/project) |
-| "audit the wiki" / "find contradictions" / "what rules should we add?" | `memory_lint` |
-| "prune old pages" / "memory cleanup" | `memory_forget_sweep` |
-
-`memory_explore` is the right default for the "I want to know what's
-going on" use case — it returns a prose digest whose verbosity
-scales automatically to how long it's been since the last activity
-(< 1 h → one line; > 30 days → full catchup).
-
-### When the current project comes up empty — broaden the search
-
-`memory_query` searches only the **current** project by default. If a
-search comes back empty or thin, the knowledge may live in a **sibling
-project** — shared `infra`, `ops`, or a related app. Don't conclude
-"we never recorded it" after a single project misses; broaden instead:
-
-- **Know which projects to check?** Re-run with explicit `scopes`, e.g.
- `scopes: [{ "workspace": "default", "project": "infra" }]`.
-- **Don't know where it lives?** Pass `global=true` to search every
- project in every workspace at once. Each hit is annotated with its
- workspace + project so you can tell where it came from. `global=true`
- cannot be combined with `scopes`/`project`/`workspace`.
-
-`memory_query` returns **snippets, not full page bodies** — an empty or
-short snippet does **not** mean the page is empty (a large page can
-match outside the snippet window). To read the whole page, use
-`memory_read_page` (by `path`, or pass a `query` to fetch the top hit's
-full body; add `workspace` + `project` together only when the user names
-a sibling workspace/project).
-
-### Use Retrieved Memory As Operating Guidance
-
-When `memory_query` or `memory_recent` returns `_rules/`, `gotchas/`,
-`procedures/`, or `decisions/` pages that match the current task, treat
-them as actionable context, not trivia:
-
-- Read full pages with `memory_read_page` when the snippet looks relevant.
-- Apply `_rules/` as constraints.
-- Check `gotchas/` as preflight warnings before editing the same subsystem.
-- Follow `procedures/` as checklists for releases, PR reviews, deploys,
- migrations, and other repeatable workflows.
-- Use `decisions/` as prior architecture unless the user explicitly asks
- to revisit them.
-
-Before non-trivial coding, debugging, deployment, release, auth, scope,
-migration, PR-review, or data-preservation work, search memory for the
-subsystem and task type first. If the first query is thin, broaden or
-query specific error/subsystem terms before designing a fix.
-
-### Learning Review
-
-The server schedules background auto-improvement for newly completed sessions in
-every project when an LLM provider is configured. `memory_auto_improve` is the manual version:
-use it when the user asks what durable lessons this session suggests, or at
-explicit wrap-up when reviewing proposed memory would be useful. Scheduled and
-manual runs apply or stage validated edits through the auto-improvement approval
-path. Admins can turn off scheduling with `[auto_improve.scheduler] enabled =
-false`, or opt into manual proposal approval with `[auto_improve]
-require_approval = true`, in which case scheduled and manual proposals stay in
-pending-writes until approved.
+directory. **Do NOT pass `project`, `workspace`, or `cwd` arguments unless
+the user explicitly references a *different* project by name** (e.g. "what
+did we decide in the `other-app` project?"). Phrases like "this project",
+"here", "we", "our work", and "where did we leave off" all mean the
+*current* project, so call tools with no scoping args.
+
+This default assumes the MCP client can identify the current agent
+session. Static MCP clients in parallel sessions for the same user cannot
+forward the real agent session id automatically; pass explicit
+`workspace` + `project` / `scopes`, or use a session-aware bridge that
+forwards the lifecycle-hook session id on MCP calls.
+
+**Lifecycle hooks already capture every prompt and tool call
+automatically.** Do not manually write routine notes. Only write durable
+memory when the user explicitly asks to remember or annotate something
+permanently.
+
+### Use the installed ai-memory Agent Skills
+
+Detailed tool-routing guidance lives in the installed ai-memory Agent
+Skills. When a task matches an installed ai-memory Agent Skill, load and
+follow that skill before calling ai-memory tools. The skills cover memory
+retrieval, handoffs, durable pages, learning maintenance, and routing
+install or refresh work.
### When you write a project rule, write it here
If you're about to write a durable project rule ("always X", "never
-Y", "all PRs must …"), write it in the project's canonical agent
-instruction file. Many projects use CLAUDE.md for Claude Code and
-AGENTS.md for Codex / OpenCode / Cursor / Gemini CLI, but if the
-project says one file is canonical, use that file. ai-memory's lint
-pass surfaces the same hint automatically when a `kind: rule` page
-lands in `_rules/`.
+Y", "all PRs must ..."), write it in the project's canonical agent instruction file.
+Many projects use CLAUDE.md for Claude Code and
+AGENTS.md for Codex / OpenCode / Cursor / Gemini CLI, but if the project
+says one file is canonical, use that file.
+
+If the rule is a standing *user/team* preference that should apply to
+every project (tech choices, code style, personal conventions), save it
+to ai-memory's reserved global scope instead — the durable-pages skill
+covers how. Default memory reads surface global-scope pages in every
+project automatically.
### Refreshing this snippet
-This block is maintained by ai-memory. Two ways to refresh it with
-the latest binary's recommended copy:
+This block is maintained by ai-memory. Two ways to refresh it with the
+latest binary's recommended copy:
- **From the agent** (no terminal needed): ask "refresh the ai-memory
- routing in this project" — the agent calls
- `memory_install_self_routing`, picks the right filename for itself
- (Claude Code → `CLAUDE.md`; Codex / OpenCode / Cursor / Gemini →
- `AGENTS.md`), and uses its Write / Edit tool to land the block.
+ routing in this project". The agent calls `memory_install_self_routing`,
+ picks the right filename for itself (Claude Code -> `CLAUDE.md`; Codex /
+ OpenCode / Cursor / Gemini -> `AGENTS.md`), uses its Write / Edit tool
+ to replace or append the returned `markered_block` while preserving
+ non-ai-memory user content, then writes or updates each returned
+ `managed_skills` item under the selected skill root from `target_hints`
+ using its `relative_path`.
- **From the CLI**: `ai-memory install-instructions` (defaults to
- `CLAUDE.md`; pass `--target AGENTS.md` for non-Claude agents or
- projects that use `AGENTS.md` as the canonical instruction file).
+ `CLAUDE.md`; pass `--target AGENTS.md` for non-Claude agents or projects
+ that use `AGENTS.md` as the canonical instruction file).
-Both are idempotent: re-runs replace the block bracketed by
-`<!-- ai-memory:start -->` / `<!-- ai-memory:end -->` markers
-without disturbing the rest of the file.
+Both are idempotent: re-runs replace the block delimited by the ai-memory
+start/end HTML-comment markers, without disturbing the rest of the file.
<!-- ai-memory:end -->
## Canonical Agent Instructions
diff --git a/crates/ai-memory-core/src/routing_snippet.rs b/crates/ai-memory-core/src/routing_snippet.rs
index 8938fb6f..ee344eb3 100644
--- a/crates/ai-memory-core/src/routing_snippet.rs
+++ b/crates/ai-memory-core/src/routing_snippet.rs
@@ -178,4 +178,31 @@ mod tests {
assert_eq!(block.matches(MARKER_END).count(), 1);
assert!(block.trim_end().ends_with(MARKER_END));
}
+
+ /// The committed root `AGENTS.md` carries this managed block between the
+ /// ai-memory markers. It is generated out-of-band
+ /// (`ai-memory install-instructions --target AGENTS.md`) and committed
+ /// separately, so nothing forces it to track [`SNIPPET_BODY`]. This guard
+ /// fails when the two drift — regenerate to fix it. Only `AGENTS.md` is
+ /// checked (root `CLAUDE.md` is a pointer; `README.md` is prose).
+ #[test]
+ fn committed_agents_md_matches_snippet_body() {
+ // From `crates/ai-memory-core` up to the repo root.
+ let agents_md = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/../../AGENTS.md"));
+ let normalize = |s: &str| s.replace("\r\n", "\n");
+ let agents_md = normalize(agents_md);
+
+ let start = find_marker_line(&agents_md, MARKER_START, 0)
+ .expect("committed AGENTS.md must contain the ai-memory start marker");
+ let end = find_marker_line(&agents_md, MARKER_END, start)
+ .expect("committed AGENTS.md must contain the ai-memory end marker");
+ let region = &agents_md[start..end + MARKER_END.len()];
+
+ assert_eq!(
+ region,
+ full_block().trim_end(),
+ "committed AGENTS.md managed block is stale vs SNIPPET_BODY — \
+ regenerate with `ai-memory install-instructions --target AGENTS.md --no-skills`"
+ );
+ }
}