feat(config): per-request config_override on memory routes

[ethanj]

Summary

Adds a per-request config_override mechanism that lets callers
pass a partial RuntimeConfig overlay on every memory API call.
Enables stateless per-request A/B, benchmark experimentation, and
external-caller tuning without env-var scattering, named-profile
proliferation, or container restarts between experiments.

Motivation

Research-side benchmark experiments (the AtomicMemory v3 parity
roadmap's Phase 1) need to vary retrieval config per experiment
without editing source or creating named profiles. The prior
approach tried a named balanced-parity profile; that was a
source edit in service of experimentation, which is the wrong
shape — config should be a parameter, not a commit. This PR moves
that config surface into the API.

Full design doc lives in the research repo at
atomicmemory-research/docs/core-repo/design/per-request-config-override.md.

What's in this PR

API contract

All four memory routes that share the body schemas
(POST /v1/memories/search, /search/fast, /ingest,
/ingest/quick) gain an optional config_override body field.

{
  "user_id": "alice",
  "query": "What did Alice say about Vite?",
  "limit": 5,
  "config_override": {
    "hybridSearchEnabled": true,
    "maxSearchResults": 12,
    "mmrLambda": 0.7
  }
}

• Flat shape: keys match RuntimeConfig field names one-for-one.
• Validation: Zod .strict().partial() — unknown keys reject with
  400; every field is optional.
• Layering: effective = { ...startupConfig, ...override }.
• Scope: just this request. No server state mutated.
• config_override absent → zero-cost path; startup config used
  as-is.

Response headers (override-only)

Requests that carry an override emit three response headers so
callers can audit what config was applied:

• X-Atomicmem-Config-Override-Applied: true
• X-Atomicmem-Effective-Config-Hash: sha256:<hex> — sorted-key
  canonical JSON fingerprint.
• X-Atomicmem-Config-Override-Keys: <sorted-csv> — flat list of
  keys present in the override.

Requests without an override emit none of the three — zero overhead
on that path.

ConfigOverride fields (45 total)

Covers every RuntimeConfig field already threaded through
MemoryServiceDeps. Split roughly 32 retrieval-side / 13
ingest-side. Deliberately excludes:

• Nested-profile fields (rerankDepth, lexicalWeight,
  repairPrimaryWeight, repairRewriteWeight) — live under
  retrievalProfileSettings.* and aren't threaded through
  deps.config. Accepting them would silently no-op, violating
  the "no degraded mode" rule in CLAUDE.md.
• Singleton-read fields (scoringWeight{Similarity,Importance, Recency}, repairSkipSimilarity) — leaf code reads these
  directly from the module singleton, not from deps.config.

Future landings that tune any of these will first lift the field
into the threaded config path (small additive change) and
automatically gain overlay support.

Implementation

• src/schemas/memories.ts — new ConfigOverrideSchema;
  extended IngestBodySchema and SearchBodySchema with
  config_override?: ConfigOverride. Because /search/fast and
  /ingest/quick reuse those schemas, all four routes auto-gain
  support.
• src/services/retrieval-config-overlay.ts (new, ~80 LOC) —
  applyConfigOverride, hashEffectiveConfig,
  summarizeOverrideKeys.
• src/routes/memories.ts — each of the four route handlers
  parses the overlay, builds EffectiveConfig, sets the three
  headers, passes to the service.
• src/services/memory-service.ts — depsFor() helper swaps
  deps.config for the call's duration. No global mutation.
• memory-search.ts, memory-ingest.ts, search-pipeline.ts,
  ingest-fact-pipeline.ts, memory-service-types.ts — accept
  effectiveConfig parameter instead of reading the singleton.
• OpenAPI regenerated.

Tests

• 26 new assertions across three files: overlay unit tests,
  schema strictness tests, route-level integration tests covering
  all four routes × (with override, without override) × headers ×
  service threading × 400 rejection.
• Full suite: 1067 tests pass, zero regressions.

Validation

End-to-end validated against the AtomicMemory R&D benchmark harness:

1. Regression check (new core code, no override): full-mini
   3-run mean matched the pre-abstraction P1-H baseline within σ
   on all metrics. hit@5 0.147 ± 0.031 vs baseline 0.140;
   judge 0.560 ± 0.060 vs 0.540; p50 352 vs 365ms; p95 560 vs
   565ms. Confirms the abstraction is transparent to requests
   without overrides.
2. P1-1 experiment (hybrid ON via override): headers confirmed
   present on all 150 QA calls (50 × 3 runs) with the expected
   effective-config hash. Gate passed per the roadmap's slice-
   aware rule: hypothesis slice (cat1 single-hop) +1.7pp judge,
   all controls within σ.

Full summary in the research repo at
memory-research/evaluation/baselines/p1-1-enable-hybrid-2026-04-23.md.

Test plan

• npm test — 1067 pass
• npm run build clean
• npx tsc --noEmit clean
• npm run generate:openapi — spec regenerated
• Live-stack smoke via curl — all three headers emitted
  correctly with and without override
• 3-run regression check on full-mini: within σ of prior
  baseline
• P1-1 experiment 3-run: hypothesis-slice positive,
  controls within σ

Backward compatibility

Fully backward compatible. Existing callers unaffected:

• config_override is optional on the body.
• No response body shape changes.
• Existing field-level env vars (HYBRID_SEARCH_ENABLED etc.)
  still override as before.

Not in scope / deferred

• SDK plumbing (the external atomicmem-sdk package gaining
  configOverride) — deferred until an external customer asks.
  The internal research adapter has it; that's the only consumer
  today.
• Deprecation of field-level env vars — separate follow-up.
• Lifting nested/singleton fields (rerankDepth, etc.) onto the
  threaded config surface — each will happen alongside its
  respective Phase-1 landing that needs it.

🤖 Generated with Claude Code