feat: stabilize prompt-visible Router Memory for production agent routing

Summary

Stabilize prompt-visible Router Memory—retrieval, injection, persistence, isolation, diagnostics, and failure behavior—for production agent workloads.

Router Memory is separate from Router Learning. It must not be used as the Router Learning experience, failure, reputation, or policy-state store.

Parent roadmap: #2287
Related: #2342, #2362, #2364, #2365, #2520, #2546

Audited current-main baseline (2026-07-15)

• src/semantic-router/pkg/memory/ defines memory stores and retrieval/extraction/consolidation behavior, with in-memory, Milvus, Qdrant, and Valkey implementations plus optional caching.
• Request/response filters retrieve prompt-visible user/conversation memory and persist extracted memory.
• The memory API enforces a user identity input, but trusted identity and multi-tenant isolation must compose with #2362/#2364.
• Request-time RouteDiagnostics already include MemoryStatus, MemoryReason, MemoryFallbackReason, MemoryFailOpen, and MemoryResultCount from #2520.
• #2365 tracks the broader supported diagnostics/receipt contract.
• Router Learning's in-process experience and Replay outcomes are different systems under router_learning_*/routerruntime.

Scope

1. Document the Router Memory lifecycle: extraction, write, retrieval, ranking, injection, consolidation, deletion, retention, and shutdown.
2. Define trusted user/tenant/conversation scope and prevent cross-scope retrieval, cache bleed, and deletion.
3. Make backend capability and consistency differences explicit; do not promise identical semantics where backends differ.
4. Bound query size, result count, injected tokens, write queues, cache cardinality, retries, and timeouts.
5. Standardize fail-open/fail-closed behavior by operation and risk, reusing the existing RouteDiagnostics fields rather than inventing a second request receipt.
6. Define startup/readiness, partial deployment, backend outage, corrupt data, cancellation, and graceful shutdown behavior.
7. Add restart/multi-replica guidance: shared stores may share memories, while local caches and Router Learning protection/experience remain separate.
8. Add privacy, retention, deletion, audit, and content-redaction documentation.

Non-goals

• No Router Learning experience snapshots, bandit/Elo state, security reputation, or cross-request policy commitments in pkg/memory.
• No unbounded prompt injection or raw memory content in default diagnostics.
• No assumption that a client-provided user ID is authenticated.
• No synchronous dependency without explicit timeout and safe degradation.

Acceptance criteria

• Store/lifecycle/capability semantics are documented and tested per supported backend.
• Trusted scope isolation covers retrieval, caches, writes, consolidation, list/get/delete APIs, and failures.
• Injection and all runtime resources are bounded.
• Existing memory diagnostics have stable enums/reasons, content-free defaults, and metrics.
• Backend outage, timeout, cancellation, partial deployment, restart, and shutdown tests exist.
• Retention/deletion behavior and operational limitations are explicit.
• Router Memory docs do not describe it as Router Learning experience or policy state.
• Maintained agent E2E coverage exercises success and fail-open behavior.

Likely change surfaces

src/semantic-router/pkg/memory/, memory-related src/semantic-router/pkg/extproc/ filters, src/semantic-router/pkg/apiserver/route_memory*.go, config, Router Replay diagnostics, deployment examples, docs, and E2E tests.

Validation entrypoint

make agent-report ENV=cpu CHANGED_FILES="<space-separated changed files>"