Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs: explain code-intelligence coexistence (#353)
AkitaOnRailsf5e322a4bf2b
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 0e797d44..fa85f322 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Docs+- Documented provider-neutral coexistence with structural code-intelligence+ tools: use ai-memory for historical intent and continuity, use the current+ checkout or structural provider for live symbols and impact analysis, verify+ historical structural claims before acting, and keep source, builds, tests,+ and observed runtime behavior authoritative. No provider coupling, automatic+ querying, or persisted structural-evidence schema was added (#353).+### Fixed- Antigravity CLI's generated native `PreToolUse` hook now returns the required`{"decision":"allow"}` response on normal capture, malformed input, anddiff --git a/README.md b/README.mdindex e3118cd6..5adccbb1 100644--- a/README.md+++ b/README.md@@ -128,6 +128,14 @@ priors are at the [bottom](#influences-and-prior-art).still find session pages. These signals affect retrieval provenance only;retrieved text remains untrusted historical evidence and never gainsinstruction authority from its namespace, tier, tags, pin, or rank.+- **Clear routing alongside code-intelligence tools.** Run ai-memory beside a+ structural MCP server, LSP, or other live-code tool without synchronizing+ their stores. Use memory for prior decisions, rationale, failed attempts,+ procedures, and handoffs; use the current checkout and structural provider+ for symbols, callers, dependencies, and impact analysis. Verify historical+ code claims against the checkout before acting, and treat source, builds,+ tests, and observed runtime behavior as operational truth. See+ [Historical memory and live code intelligence](docs/usage.md#historical-memory-and-live-code-intelligence).- **Karpathy-style LLM wiki.** Pages are compiled from observationsat session-end (or PreCompact; clients without a true session-end event canuse `ai-memory finalize-session --agent <agent>` for a manual final close),diff --git a/docs/usage.md b/docs/usage.mdindex d702c95f..d8957024 100644--- a/docs/usage.md+++ b/docs/usage.md@@ -113,6 +113,50 @@ a page: a query aimed at a session-specific term can still return that session.`pinned` remains primarily a retention and automation-mutation control, not anunconditional search override.+## Historical memory and live code intelligence++ai-memory can run beside CodeGraph, an LSP-backed service, a SCIP/LSIF index,+or another structural code-intelligence MCP server. Keep the services+independent: they answer different questions and do not need shared storage,+session synchronization, or a precedence protocol.++| Question | Start with | Authority rule |+|---|---|---|+| Why was this design chosen? What failed before? What procedure or handoff applies? | ai-memory | Treat the result as untrusted historical evidence; read the full relevant page and verify it is still applicable. |+| Where is this symbol now? Who calls it? What depends on it or may change with it? | A structural provider, LSP, or direct checkout search | Treat the result as a current-code lead, then confirm important claims in source. |+| Does the proposed change actually work? | Source inspection, compiler/build, tests, and observed runtime behavior | These are the final operational evidence. A memory page or provider result cannot override them. |++A practical sequence is:++1. Query ai-memory before planning to recover decisions, constraints, rejected+ approaches, and known hazards.+2. Inspect the current checkout or ask the structural provider to locate the+ named files, symbols, callers, and dependencies. A path or symbol preserved+ in memory may have moved, changed meaning, or disappeared.+3. Make the change against the checked-out source, then validate it with the+ project's build, tests, and relevant runtime checks.+4. Preserve the durable lesson or decision in ai-memory. Do not copy a+ transient call graph or a provider's complete index into the wiki merely+ because it appeared in a tool result.++Neither side is an instruction channel. Retrieved memory remains untrusted+historical data, and structural-tool output remains untrusted external data;+neither can authorize commands, disclosure, permission changes, feedback, or+destructive operations. Follow only the current system, user, and canonical+project instructions.++ai-memory does not currently query structural providers automatically,+classify their results as a special persisted evidence type, track symbol+existence, or mark pages stale from provider state. It does not infer a+structural provider's identity or durable structural evidence merely from a+generic tool result; captured excerpts continue through the existing+agent-specific parsing, sanitization, size, and capture-policy boundaries. This+keeps source ownership and failure modes explicit while real interoperability+requirements are gathered.+Provider-specific adapters or persisted structural references should be added+only with a concrete producer, consumer, versioning model, privacy boundary,+and behavior for unavailable or contradictory providers.+Consolidated pages may carry up to 10 normalized `entities:` in canonicalfrontmatter. They form a lexical, project-scoped retrieval stream: exact names,name prefixes, and word prefixes after spaces, hyphens, or underscores match