Retrieval API¶

`GET /api/context/{project_id}/relevant`¶

Return the memories most relevant to a query, ranked, with per-item scores.

This is the endpoint you build prompts from.

Auth: API key or session. Unknown project key → 404.

Path and query parameters¶

Param	In	Default	Notes
`project_id`	path	—	Your project key
`query`	query	`""`	Empty → all candidates get `similarity = 1.0`
`limit`	query	`5`	Max memories returned. No server-side cap.

Example¶

curl -sG https://api.venkai.fr/api/context/billing-service/relevant \
  -H "Authorization: Bearer $VENKAI_API_KEY" \
  --data-urlencode 'query=which database did we pick' \
  --data-urlencode 'limit=2'

{
  "project_id": "billing-service",
  "query": "which database did we pick",
  "memories": [
    {
      "id": "ctx_cc55e4a7bbc5",
      "org_id": "org_1f200d429c50",
      "project_id": "billing-service",
      "agent_key": "planner",
      "type": "decision",
      "content": "We use Postgres, not MongoDB, because the ranking query needs joins.",
      "confidence": 0.8,
      "importance": 0.9,
      "access_count": 0,
      "last_accessed_at": null,
      "created_at": 1787007131.3763673,
      "updated_at": 1787007131.3763673,
      "metadata": {"ticket": "ARCH-14"},
      "score": 0.4789,
      "similarity": 0.1348,
      "justification": "semantic similarity 0.13 (HashingEmbeddingProvider, 128d)"
    },
    {
      "id": "ctx_f6f282cb1a2f",
      "type": "constraint",
      "content": "The retrieval endpoint must answer in under 200 ms at p95.",
      "importance": 0.8,
      "score": 0.4,
      "similarity": 0.0,
      "justification": "semantic similarity 0.00 (HashingEmbeddingProvider, 128d)"
    }
  ]
}

Response¶

Field	Notes
`project_id`	Echo of your key
`query`	Echo of the query
`memories[]`	Ranked descending by `score`. Never contains `embedding`.

Every memory carries three extra fields on top of the stored ones:

Field	Range	Meaning
`similarity`	0–1	Cosine between query and memory embedding. `1.0` when no query; `0.0` when vectors are incompatible.
`score`	0–1	`0.40·similarity + 0.20·recency + 0.25·importance + 0.15·frequency`
`justification`	string	Names the provider and its dimension

Behaviour worth knowing¶

No relevance floor. Nothing is dropped for scoring badly. Ask for limit=10 on a project with 10 memories and you get all 10, however unrelated. Apply your own cutoff on score.

limit is a count of memories, not a token budget. Ten 8000-character memories satisfy limit=10. Enforce a character or token budget client-side — see Context selection.

Reading does not mutate. access_count, last_accessed_at and updated_at are unchanged by retrieval, deliberately (Ranking).

Deterministic. No model call in the read path. Same store, same query, same result.

Candidate ceiling. Candidates are capped at VENKAI_RETRIEVAL_MAX_CANDIDATES (default 10 000), truncating oldest first. The server logs a warning when it truncates — it is never silent, but you only see it if you run the instance.

Empty query is a legitimate call. ?limit=5 with no query ranks by recency + importance alone and skips the query embedding entirely — a cheap "what matters here right now".

Errors¶

Status	When
`401`	Missing or invalid credential. Never an empty list — `{"memories": []}` means authenticated and genuinely empty.
`404`	Project key does not exist in this organization. Keys are created by writes only.
`429`	Rate limited (production only)

Compared with `GET /api/context/{project_id}`¶

	`/relevant`	list endpoint
Ordering	by `score`	`created_desc`
Scoring fields	✅	✗
Filters (`type`, `agent`, `q`)	✗	✅
`limit` cap	none	200
Pagination	✗	`offset`
Use for	prompts	dashboards, audit, export

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