Retrieval tuning

Tune semantic recall using representative queries, lifecycle-aware inspection, and bounded prompt budgets.

Start with an evaluation set

Collect representative queries, expected facts, acceptable alternatives, and known negative examples. Tune against this set rather than one successful demo query.

Primary controls

limit: maximum memory candidates fetched before final prompt selection.

minSimilarity: vector-search floor; lowering it increases recall and noise.

tokenBudget: maximum approximate fact-block tokens assembled into the prompt.

similarityWeight: how strongly semantic match affects ranking.

confidenceWeight: how strongly extraction confidence affects ranking.

tags, tagMode, and scope: which memory population is eligible.

Tune in order

Confirm ingestion produced the expected atomic memory.

Confirm session, tags, and lifecycle state.

Inspect raw similarities using a moderately permissive threshold.

Adjust ranking weights only after candidate quality is understood.

Set the token budget from downstream prompt constraints.

tuning.ts

const result = await agent.recall(query, {
  limit: 10,
  minSimilarity: 0.55,
  tokenBudget: 1200,
  scoring: {
    similarityWeight: 0.7,
    confidenceWeight: 0.3,
  },
});

Debug missing recall

Wait for inline or queued ingestion to complete.

Check whether extraction created memory nodes, not only a topic summary.

Use the vocabulary of the stored fact in a diagnostic query.

Inspect forgotten, decayed, superseded, and suppressed states in a snapshot.

Check tag normalization and recall scope.

Use Studio Prompt Preview with the same query and settings.

Recall caching

When configured, MemoGrafter caches only raw vector-search results, not final prompts or complete retrieval results. Keys include session, limits, threshold, scope, tag mode, normalized tags, and an embedding hash. TTL defaults to 90 seconds and is clamped to 60–120 seconds.

Redis failures fall back to PostgreSQL search.

Successful lifecycle changes clear recall cache entries.

Different token budgets still assemble fresh prompt output.

Caching helps repeated stable queries; it does not solve slow ingestion or poor embeddings.

Measure

Fact precision and recall against expected results.

Empty-result and irrelevant-result rates.

Prompt token count and downstream answer quality.

Vector-search latency and cache hit behavior.

Performance across tenants, tags, and session sizes.