Recall Tuning

CortexDB's recall pipeline can run several retrieval channels and fuse them with reciprocal rank fusion. About a dozen env vars expose knobs into that pipeline; another two dozen are compiled constants tuned against LongMemEval-S and LoCoMo.

Most deployments shouldn't tune any of these — the defaults match the published 93.8% number.

The pipeline at a glance

Query
  ├─► Query routing ─────────────────────────► question_type
  ├─► (optional) HyDE multiquery expansion ──► N hypothesized passages → query vectors
  ├─► (optional) Multihop query planner ─────► M follow-up queries (LLM)
  ├─► Parallel retrieval channels:
  │      • Vector (HNSW)            [default]
  │      • Fulltext (BM25 + WordNet)[default]
  │      • Entity-name (exact/fuzzy)
  │      • Synonym
  │      • Graph BFS (KG edges)     [needs KG + enrichment]
  │      • Temporal (recency + decay)
  ├─► Reciprocal rank fusion (RRF, k=60) ──► fused candidate list
  ├─► Cross-encoder rerank (optional) ──► reranked top-K  [needs Cohere]
  └─► Build response pack (citations, beliefs, episodes)

Skipping a stage saves latency at the cost of recall accuracy.

Graph retrieval

The KG channel walks edges around entities mentioned in the query.

Disable on the voice/realtime hot path (trade ~-3 pp for ~150 ms); bump TOP_K to 80/240 for entity-rich queries. Non-overridable constants: GRAPH_RETRIEVAL_MAX_ENTITIES = 48, GRAPH_RETRIEVAL_MAX_EDGES = 512, GRAPH_RETRIEVAL_MAX_EPISODES = 256, GRAPH_WEIGHT = 0.20.

HyDE multiquery expansion

HyDE asks an LLM to write a hypothetical passage that would answer the query, then embeds that instead of (or with) the literal query.

Set the disabled-types list to all four types to disable HyDE entirely (saves ~150–400 ms, loses ~1–2 pp on phrasing-mismatch queries). CORTEX_HYDE_PASSAGES_MS=3 uses temperatures [0.3, 0.6, 0.9] for wider coverage at 3× HyDE cost.

Multihop query planner

For complex queries, an LLM plans 2–N follow-up queries, then runs all of them through retrieval.

Empty the types list for latency-sensitive deployments (saves 1–3 LLM round-trips, loses ~1–3 pp on complex multi-session); QUERY_COUNT=6 + FANOUT=8 for offline QA.

Salience prior

A per-memory importance score updated by access patterns; the ranker can use it as a recency prior.

Bump to 0.20 for "recently relevant" agents; set 0.0 for historical-archive workloads (the right answer might be years old).

Recency ordering

Salience is a prior on ranked retrieval. order=recency is different — it replaces ranked retrieval for the events layer with a timeline tail: the scope's newest events by observed_at, rendered newest-first. Set it explicitly on /v1/recall or /v1/answer, or let /v1/answer infer it for "recent/latest" questions. It's the right tool for "what's the latest…" reads, where relevance ranking returns the most-repeated items and can drop the newest ones.

Entity-vector seeding

Take the query's entity mentions, look up their canonical vectors, use those as additional query vectors.

Enable for queries with named entities that don't match stored phrasing exactly. Constants: ENTITY_VECTOR_SEED_TOP_K = 10, ENTITY_VECTOR_SEED_MIN_SIMILARITY = 0.40, ENTITY_VECTOR_SPAN_LIMIT = 5, ENTITY_VECTOR_PER_SPAN_TOP_K = 5.

Reranker

A cross-encoder that re-scores the top ~25–40 fused candidates as (query, candidate) pairs.

cohere + COHERE_API_KEY → ~+2 pp on noisy sets, ~$0.001/recall, +80–200 ms. local + MODEL_PATH → free but ~200–500 ms on CPU. Leave disabled for voice/sub-100ms paths.

Question-type executor switches

The /v1/answer endpoint routes queries through type-specific executors. These flags disable specific paths for A/B testing.

Synchronous-write kill switches

These affect the write path — and thus when recall has the data available.

Disable for batch ingest (see the Batch profile) or write-heavy workloads that tolerate 30–60 s recall lag.

Memory evolution (methylation + consolidation)

Background jobs that prune low-utility memories and consolidate related ones.

Tighten methylation for chatty agents (INACTIVITY_HOURS=72), loosen for archival (INACTIVITY_HOURS=720); CORTEX_SCHEDULER_DISABLE=1 disables the whole scheduler for stable benchmark evals.

Compiled constants you can't (yet) override

Tuned against LongMemEval-S + LoCoMo; file an issue to request promotion to an env var.

Latency budget breakdown (default config)

Rough p50 for a single /v1/recall against a ~100K event scope:

HyDE and multihop dominate wherever they run — disabling them is the highest-leverage latency win for voice/realtime.

Next steps

• Profiles & Presets — the Voice profile for a low-latency config
• Embeddings — vector dim and model choice
• Benchmarking — how 93.8% was produced with these defaults