Skip to content

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

Rust

Merge branch 'main' into release/2.2

AkitaOnRails74e407b370c5
diff --cc CHANGELOG.md
index 1b6e786f,6e5b750d..4c736a77
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@@ -7,77 -7,14 +7,84 @@@ and this project adheres to [Semantic V
## [Unreleased]
+### Added
+- Page-grain ingestion windows (`pages.valid_from` / `valid_to`, V62) and
+ a second `as_of` stream: `memory_query(as_of=T)` now fuses the entity
+ timeline with version-filtered full-text search over the page versions
+ alive at T, using the default path's RRF (k=60) plus the same bounded
+ authority adjustment — current-index relevance over knowledge valid at T. This
+ answers entity-less pages and paraphrased audit questions ("which
+ database were we on during the outage?") that the entity-only lookup
+ missed. `explain=true` reports both streams (`streams_active:
+ ["entity", "fts"]`) with per-stream ranks and RRF contributions.
+ Vector, graph, and the raw-observation fallback stay out of audit mode;
+ the default (no `as_of`) path is unchanged. Every retire path
+ (supersede, decay, reorg graveyard, move-regenerate) closes both grains
+ in the same transaction, and the V62 backfill closes successor-less
+ retirements at the decay marker, existing entity-link close, or
+ `updated_at` fallback, preserving recorded reorg/move history.
+ Phase B world-time stays deferred. (#656)
+- `[retrieval]` section with two opt-in ranking signals, both off by default
+ so unconfigured stores rank exactly as before. `query_intent` routes
+ lexically session-recall queries ("上次 / 之前那次…的会话 / last time /
+ yesterday …") past the default session-page authority penalty
+ (×0.77 combined kind/tier), with `session_recall_bonus` (default 0.25)
+ sizing the lift; `abstract_vectors` adds a fifth RRF stream over the new
+ `page_abstract_embeddings` table (V61) — the L0 layer: a page's
+ frontmatter `abstract:` line is embedded on its own, at write time when an
+ embedder is attached and by the same backfill as the body otherwise
+ (a one-line summary embeds far more sharply than a
+ multi-thousand-character body). Measured on a 138-query golden set over a
+ production two-year wiki (FTS5 + entity + vector + graph, mis-tei
+ Qwen3-Embedding-8B): hit@1 0.609 → 0.746 (+22%), NDCG@10 0.782 → 0.879
+ (+12%) with both enabled; every unrouted category keeps its exact
+ baseline ordering. Cross-checked on an independently built 99-query
+ golden set against the same store: hit@1 0.556 → 0.626, NDCG@10
+ 0.712 → 0.779 (+9.4%). Both signals are visible per hit in
+ `memory_query(explain=true)` (`intent`, `intent_boost`,
+ `abstract_rank`, `rrf.abstract`). (#672)
+- `memory_handoff_list` lets no-stdout and MCP-only clients inspect open
+ project handoffs without claiming or expiring them, then
+ `memory_handoff_accept` can claim that exact `handoff_id` once. Grok,
+ Zero, and other clients that discard SessionStart stdout no longer have
+ to recover a baton by blindly accepting the latest row. Listing is
+ owner-filtered like accept (own plus shared; root-only `any_owner`);
+ it is not a second claim path, and Grok SessionStart still does not
+ fetch `/handoff`. (#664)
+- `install-instructions --compact` writes a slimmer managed routing block for
+ projects that already have the detailed ai-memory Agent Skills installed. The
+ compact block keeps the same start/end markers (so refresh/uninstall still
+ find it), the untrusted-history security scaffold, and the cross-harness
+ memory-of-record guidance; `full_block` and the default remain unchanged.
+ (#675)
+- `memory_install_self_routing` accepts `compact: Option<bool>` so agent-driven
+ refreshes of a compact-installed file preserve the compact routing block
+ instead of rewriting it back to full. (#685)
+- The `openai-compat` provider now sends OpenRouter's app-attribution
+ headers (`HTTP-Referer`, `X-Title`) by default when its base URL points
+ at `openrouter.ai`, so ai-memory's usage shows up on OpenRouter's app
+ leaderboard. An explicit `AI_MEMORY_LLM_HEADERS` entry for either header
+ still wins, and a non-OpenRouter compat endpoint (Ollama, vLLM, LM
+ Studio) never receives them. (#686)
+- `ai-memory run` now accepts any `claude*`-prefixed harness name
+ (`claude-corp`, `claude-personal`, ...), all resolving to the same
+ `ManagedHarness::Claude`/`AgentKind::ClaudeCode` — no new session store,
+ migration, or agent kind. This is for callers juggling more than one
+ Claude account (e.g. Corporate and Personal): name each account's `PATH`
+ wrapper script `claude-<account>` and pair it with `--executable
+ claude-<account>` (bare names already resolve through `PATH`) so
+ `ai-memory run claude-corp --executable claude-corp` and `ai-memory run
+ claude-personal --executable claude-personal` each launch the right
+ binary while reading clearly in shell history (#687).
+
### Changed
+ - The managed routing snippet distinguishes a reviewed decision record kept in
+ the repository (an ADR directory, a Keep the Why `context/` tree) from a
+ harness-local memory store: decisions go into the repo's record under its
+ convention, ai-memory keeps recall, handoffs and session history and does not
+ duplicate the record as a page. `docs/usage.md` ("Repo-native decision
+ records") and `docs/marker-file.md` say to list such a directory in
+ `[capture] ignore_paths`, and why (#700).
- The managed routing snippet now states that Claude Code loads `CLAUDE.md` and
does not read `AGENTS.md`: a project whose canonical instruction file is
`AGENTS.md` needs a bare `@AGENTS.md` import line in `CLAUDE.md`, or the rules
@@@ -87,10 -24,30 +94,34 @@@
now uses the import instead of a prose pointer (#680).
### Fixed
+- Preserved recorded entity-link retirement timestamps when backfilling
+ page ingestion windows for historical reorg/move-regenerate pages,
+ preventing empty page windows when `updated_at` still held creation
+ time. Clarified current-index ranking and snapshot-based rollback. (#682)
+ - A `purge-session` whose page-file cleanup failed was undone by the next
+ watcher pass. The cleanup failure is reported in `files_failed` and leaves
+ the database rows deleted while `sessions/<id>.md` is still on disk; nothing
+ on the reindex path consulted the `purged_sessions` tombstone, so the
+ reconcile tick 30 seconds later indexed the leftover file and the purged
+ session's body was searchable again. The wiki reindex now skips a page whose
+ session is tombstoned, the way it already skips a tombstoned scope, loading
+ the tombstones once per directory per pass rather than once per page. The
+ pass reports them as `skipped_purged_sessions` (#701).
+ - The Docker wrapper (`bin/ai-memory`) now forwards `GEMINI_API_KEY` and
+ `GOOGLE_API_KEY` into the container. Every other provider credential was on
+ the `-e` forwarding allowlist, but these two were missing, so
+ `AI_MEMORY_LLM_PROVIDER=gemini` (or the gemini embedder) reached the server
+ while its key did not — the process then failed with `provider not
+ configured: GEMINI_API_KEY or GOOGLE_API_KEY` even though the operator had
+ exported it (#698).
+ - `serve` no longer re-archives the whole data directory on every boot once the
+ pre-migration backup receipt's archive has been deleted and auto-improve
+ `_pending/` sidecars exist. The OKF conformance scan that feeds the backup
+ gate flagged those staging sidecars (which carry no frontmatter and are never
+ migrated — SQLite owns their approval state) as nonconformant, so it kept
+ falling through to a full archive. The scan now skips the project-root
+ `_pending/` subtree — a nested `notes/_pending/` page still migrates — matching
+ the watcher indexer and the existing ledger skip (#695, same class as #669).
- A bare `LLM_BASE_URL` in the environment no longer redirects providers that
talk to a fixed vendor endpoint. The variable is a cross-tool convention an
operator exports once for a local Ollama, and ai-memory fed it to every