Skip to content

Retrieval

Retrieval is finding the memories that match a task and ranking them. Deciding what actually goes into the prompt is context selection — a related but separate question.

What happens on a query

flowchart LR
  Q["GET /api/context/{project}/relevant<br/>?query=…&limit=N"] --> S["Memories of this project<br/>in your organization"]
  S --> E["Relevance + context signals"]
  E --> T["Top N, best first"]
  T --> OUT["memories[] with score,<br/>similarity, justification"]
  • An unknown project key returns 404.
  • Only memories belonging to your organization are ever considered.
  • No language model is called. The same store and the same query produce the same list.
  • Reading does not modify any memory.

How relevance behaves today

Beta

On the hosted service, relevance currently favours shared wording between the query and the memory over pure paraphrase. A memory that says "We use Postgres" matches a query containing "Postgres" far better than a query about "the database". Two practical consequences:

  • similarity values can look low even for clearly on-topic memories. Compare scores within a response rather than reading them as absolute.
  • Write memory content with the vocabulary your agents will use when they ask, and phrase queries with concrete terms.

Importance and recency still shape the ranking, so a high-importance decision can rank first even with a modest similarity. Stronger paraphrase-level matching is on the roadmap and will not change the API.

With and without a query

Call Ranking uses
?query=… Relevance to the query plus context signals
no query Context signals only — "what matters in this project right now"

The two read endpoints

GET /api/context/{project} GET /api/context/{project}/relevant
Ordering created_desc (configurable) by score
Filters type, q, agent, offset none
Scoring none yes
Page cap 200 none — limit is respected as given
Returns context[], decisions[], count, total, offset memories[]
Use for dashboards, audit, export prompts

q on the list endpoint is a substring filter, not a ranking signal. It is not a cheap /relevant.

Large projects

Retrieval is designed for projects of up to several thousand memories. Very large projects are subject to a service limit on how many memories a single query considers, favouring the most recent ones. If a project is heading towards tens of thousands of memories, split it by domain (one project per service or agent team), or contact us.

Latency

There is no published latency benchmark for Venkai, and this documentation does not quote one. Measure on your own data, from your own region, before designing around a number.