Memory (Implementation): backend selection, fallback, healing, scope guard

This page complements the concept-level Memory system with implementation boundaries.

Code entry points (optional)

• src/memory/backend-config.ts
• src/memory/search-manager.ts
• src/memory/qmd-manager.ts
• src/agents/tools/memory-tool.ts
• src/gateway/server-startup-memory.ts

The three-layer split (recommended)

1. config parsing (backend/citations/limits/scope)
2. manager acquisition (primary qmd → fallback builtin)
3. tools (memory_search / memory_get) with safe degradation

The key self-healing point: evict cached primary on failure

On primary failures:

• mark primary failed
• close primary
• evict the cache entry so a future request can recreate qmd

Scope guard: policy boundary, not backend failure

When the scope denies a search, return empty results (or disabled) without crashing the run.

Failure modes and troubleshooting

• Missing qmd binary/deps: verify automatic fallback to builtin and inspect Logging.
• Memory leaking into group contexts: audit scope rules and how session keys are matched (see Sessions).

Acceptance checks

1. primary failures fall back without breaking the main run.
2. cache eviction enables recreating primary later.
3. scope-denied searches return empty results (no errors).
4. tools degrade safely (disabled), not fatal throws.