fix(recall): make cold recall fast on large, long-lived stores

[audreyt]

What

Two changes that make cold mnemon recall fast on large, long-lived stores:

1. feat(memory): the Ollama client sends keep_alive (new MNEMON_EMBED_KEEP_ALIVE, default 30m; not sent to OpenAI-compatible servers). A new mnemon gc --compact runs VACUUM and reports the file size before and after.
2. fix(recall): cuts the per-node SQLite reads in beam search:
   • neighbours resolve from the active-insight snapshot recall already loaded, instead of one GetInsightByID each;
   • each node's edges are cached across anchors within one recall;
   • the known-entity set comes from the same snapshot (IntentAwareRecallFrom, store.KnownEntities), so the insights table is scanned once;
   • new covering indexes answer GetNeighborEdges from the index alone, in a fixed order;
   • a small partial index of supersedes edges serves the superseded check;
   • both open modes set mmap_size.

Why

On a large, long-lived store, a cold recall took about 5.8s before this change. The time was mostly waste:

Cost	Share	Cause
Reloading the embedding model	~2.4s	Ollama's default 5-minute keep_alive unloads it between agent turns
Reading a fragmented database	~3.2s	Recall updates access counters on every hit and nothing ever vacuums, so table pages scatter and cold reads run at random-I/O speed. VACUUM alone cut a cold-cache recall from ~3.6s to ~1.4s.

Profiling the remaining time found several other costs in beam search:

• For one query it made ~3.7k GetInsightByID calls and ~1k uncached GetEdgesByNode calls, around 440ms even when warm.
• Edge lookups went through single-column indexes, so each edge row was a random read into the table.
• The known-entity set was a second full scan of the insights table.

Measurements after the recall change (Apple M4, embedding model already loaded, medians of 5–7 runs over three queries):

	before	after
warm	0.82–0.87s	0.53–0.56s
page cache purged	1.92–1.96s	1.22–1.53s

Each query returned the same top-10 set.

Notes for review

• Migration. migrateEdgeRecallIndexes runs last on every writable open, because the edge-table rebuild migrations recreate the single-column indexes. It adds idx_edges_source_cover, idx_edges_target_cover and the partial idx_edges_supersedes, and drops idx_edges_source / idx_edges_target. The (id, edge_type) indexes still serve plain id lookups. The first open builds the indexes (under a second with hundreds of thousands of edges). The file grows by ~15%.
• Read-only opens skip migrations. The superseded lookup therefore falls back to the existing scoped IN (...) query when idx_edges_supersedes is absent (covered by a test). INDEXED BY is needed because SQLite's planner will not choose a partial index for this query by itself.
• Ordering. GetNeighborEdges orders by weight DESC plus a key tiebreak. Beam search stops at a visit budget, so which neighbours it reaches depended on index order. This makes it deterministic, and it can reorder lower-ranked results relative to before.
• Upstream behaviour kept. Self-supersession is still ignored (source_id != target_id); the partial index covers (target_id, source_id) so the filter stays index-only.
• When to compact. gc --compact is explicit rather than automatic, because free-page counts alone do not reveal page scattering. It needs an exclusive lock and briefly doubles disk use.

Checklist

• Deterministic tests pass (make test)
• Relevant E2E/process/Docker boundaries pass (make test-integration, when affected)
• New/changed behavior is covered by tests: keep_alive default, override and OpenAI omission; compaction; neighbour order; query plans use the covering and partial indexes; known-entity parity; missing-index fallback
• Documentation updated: README, USAGE and zh docs cover MNEMON_EMBED_KEEP_ALIVE and gc --compact
• User-facing release-note impact: new MNEMON_EMBED_KEEP_ALIVE (default keeps the model loaded 30 minutes); new mnemon gc --compact; faster recall; a one-time index migration on the first writable open

[Copilot]

Copilot review overview

🔵 Needs a closer look

Durable-store maintenance and budget-sensitive traversal need human validation, and a transaction deadlock remains unresolved.

Review effort: Balanced
Findings: 1

Open (1)

• Reject Compact calls inside transactions to prevent deadlock · New

What changed in this PR

Improves cold Memory recall by reducing database reads and embedding-model reloads, with explicit store compaction.

Changes:

• Adds configurable Ollama model retention and gc --compact.
• Reuses insight snapshots and cached transitions; adds recall indexes and memory-mapped reads.
• Adds regression tests and English/Chinese documentation.

File	Description
README.md	Documents model retention setting.
internal/​memory/​store/​recall_index_test.go	Tests indexes, ordering, entity parity, and fallback.
internal/​memory/​store/​node.go	Extracts known entities from loaded insights.
internal/​memory/​store/​edge.go	Adds optimized neighbor and supersession queries.
internal/​memory/​store/​db.go	Adds recall indexes and memory-mapped reads.
internal/​memory/​store/​compact.go	Implements checkpointed compaction.
internal/​memory/​store/​compact_test.go	Tests space reclamation.
internal/​memory/​store/​compact_busy_test.go	Tests busy and read-only rejection.
internal/​memory/​search/​recall.go	Reuses snapshots and caches transitions.
internal/​memory/​search/​recall_transition.go	Ranks transitions before visit limits.
internal/​memory/​search/​recall_budget_test.go	Tests budget-sensitive ranking.
internal/​memory/​search/​integration_test.go	Adapts traversal tests.
internal/​memory/​embed/​ollama.go	Sends configurable Ollama retention.
internal/​memory/​embed/​ollama_test.go	Tests retention defaults and protocol handling.
docs/​zh/​USAGE.md	Documents new options in Chinese.
docs/​zh/​README.md	Documents model retention in Chinese.
docs/​USAGE.md	Documents compaction and model retention.
cmd/​memory/​recall.go	Shares the active-insight snapshot.
cmd/​memory/​gc.go	Exposes compaction and size reporting.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.