Core Concepts

Retrieval Pipeline

Recall is hybrid scoring, not pure cosine similarity. Each candidate gets seven feature scores (semantic, recency, importance, quality, decay, usage, graph) blended by configurable weights. The query is auto-routed to a low / medium / high computation tier based on its complexity.

The seven signals

Signal	What it measures	Default weight
semantic	Cosine similarity between query and memory embedding	0.40
recency	Exponential decay over age (half-life 30d)	0.15
importance	Caller-supplied importance (0-1)	0.10
quality	quality_score from intelligence pipeline	0.10
decay	Inverse access frequency for stale memories	0.05
usage	Recent successful recalls (last 14d)	0.10
graph	Multi-hop neighborhood relevance	0.10

Note

Override weights per query with the weights object on /memory/query. Values are normalized so they sum to 1.

Flow

Computation tier routing

The router inspects the query before scoring:

low — short queries (< 6 tokens), no filters: vector top-K only, no graph expansion. ~5 ms p50.
medium (default) — full feature scoring with graph depth 2. ~30 ms p50.
high — graph depth 3, cross-cluster reranking, summary expansion. ~120 ms p50, used for synthesis and decision panels.

Force a tier with computation_tier: "high" in the request body. Costs scale linearly with tier (see Cost Optimization).

Filters

JSON

{
  "query": "MFA login issues",
  "k": 5,
  "filters": {
    "sources": ["support_ticket", "slack"],
    "tags": ["incident"],
    "since": "2026-04-01T00:00:00Z",
    "tier": "hot",
    "include_summaries": true
  },
  "weights": { "semantic": 0.5, "recency": 0.3, "importance": 0.2 },
  "traversal_depth": 2,
  "session_id": "ses_01HMRT…"
}

Sessions

Pass session_id across consecutive queries to enable cross-query context. The ranker boosts memories that scored well in the same session and persists the routing tier so a follow-up question doesn’t demote unexpectedly.

Response shape

JSON

{
  "memories": [
    {
      "id": 18420,
      "text": "Customer 8821 reported login failures after MFA reset…",
      "score": 0.91,
      "scores": {
        "semantic": 0.88,
        "recency": 1.00,
        "importance": 0.60,
        "quality": 0.71,
        "decay": 0.94,
        "usage": 0.30,
        "graph": 0.55
      },
      "explain": ["matched topic 'authentication'", "recent (12h)"],
      "tier": "hot"
    }
  ],
  "computation_tier": "medium",
  "session_id": "ses_01HMRT…",
  "latency_ms": 28
}

Edge cases

Empty result — a successful 200 with memories: []. This is also returned in silent quota mode; check X-MemorySync-Silent: 1 response header to disambiguate.
Project mismatch — if X-Project-ID is missing, the API returns memories from the org’s default project; cross-project results are never returned.
Filter starvation — if filters reduce candidates below k, the response includes filter_relaxed: true with the relaxed predicates.

Advanced

Graph traversal

Memories are connected via a sparse graph built from shared entities and topic clusters. Recall expands the candidate set by walking up to traversal_depth hops from the top vector hit; this surfaces decisions that share an entity but not phrasing.

Optional reranker

Enable rerank: true to apply a cross-encoder re-rank on the top 50 candidates. Adds 80–150 ms but improves precision on ambiguous queries. Costs are billed recorded as a separate rerank counter on the usage ledger.

← Previous

Embeddings Explained

Recall Logs