Skip to content

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.md
index 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, and
diff --git a/README.md b/README.md
index 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 gains
instruction 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 observations
at session-end (or PreCompact; clients without a true session-end event can
use `ai-memory finalize-session --agent <agent>` for a manual final close),
diff --git a/docs/usage.md b/docs/usage.md
index 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 an
unconditional 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 canonical
frontmatter. They form a lexical, project-scoped retrieval stream: exact names,
name prefixes, and word prefixes after spaces, hyphens, or underscores match