Ranking¶

Every retrieved memory carries a score, and results are returned best first. This page explains what drives that score from the caller's side, and which inputs you control.

What goes into the score¶

Venkai ranks candidate memories by combining semantic relevance to your query with additional context signals:

Signal	What it captures	Who controls it
Relevance	How closely the memory's `content` matches the query	You, through how memories and queries are worded
Importance	How much this memory matters, as stated at write time	You, through `importance` (0–1)
Recency	How current the memory is	Time — it fades gradually over weeks
Usage	Confirmed usefulness over time	Explicit feedback, not retrieval

The exact way these signals are combined is internal and may evolve without changing the API. What stays stable is the contract: score is in [0, 1], higher means more relevant for this query, and results are sorted by it.

Implementation may evolve

Ranking improvements ship without a change to the endpoints or the response shape. Do not hard-code assumptions about absolute score values across releases; compare scores within a single response.

The signals, from your side¶

Relevance¶

Driven by the content of the memory and the query you send. With no query, relevance is neutral and ranking falls back on the other signals — useful for "what matters in this project right now".

See Retrieval for how relevance behaves on the hosted service today.

Importance¶

Exactly the value you sent at write time. It does not decay and it is not learned. It is the strongest lever you have over ranking: a hard constraint written months ago at a high importance keeps surfacing, while low-importance chatter drops away.

Value	For
`0.9–1.0`	Hard constraints, irreversible decisions
`0.6–0.8`	Decisions with a stated reason
`0.4–0.5`	Ordinary facts (the default is `0.5`)
`0.1–0.3`	Nice-to-know, preferences, ephemera

Setting everything to 0.9 is the same as setting nothing.

Recency¶

Newer memories get a boost that fades gradually over weeks. After a couple of months, an old memory survives on relevance and importance alone. That is by design: ageing is handled by ranking, not by deletion.

Usage¶

A signal reserved for memories that have proven useful. It is not fed by retrieval (see below), so for most memories today it plays little role.

Retrieval does not reinforce itself¶

Retrieving a memory does not make it rank higher next time. access_count and last_accessed_at are left untouched by /relevant.

flowchart LR
  A["memory retrieved"] --> B["counts as usage"]
  B --> C["ranks higher"]
  C --> D["retrieved again"]
  D --> A
  style A fill:#7f1d1d,color:#fff
  style D fill:#7f1d1d,color:#fff

If retrieval counted as usage, whatever surfaced first would keep surfacing, regardless of whether it helped. The top of the list would lock in and stop rotating. Venkai avoids that loop on purpose.

Planned — usage earned only from confirmed usefulness, via explicit feedback.

Tuning what you can¶

The ranking policy is not configurable per request. The inputs are:

Want	Do
Foundational rules to always surface	`importance` ≥ 0.9
Better matching	Write `content` as a full statement using the terms your agents will query with
Less noise from old chatter	Write ephemera at `importance` ≤ 0.2 — recency drops it out on its own
Deterministic subsets	Use the list endpoint with `type=`, not `/relevant`