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 → ranking uses context signals only
`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": "relevance 0.13 to the query"
    },
    {
      "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": "relevance 0.00 to the query"
    }
  ]
}

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	Relevance of the memory to the query. `1.0` when no query was given.
`score`	0–1	Overall ranking value: relevance combined with context signals (importance, recency, usage). Compare within a response, not across releases.
`justification`	string	Human-readable explanation. Informational — do not parse it; its wording may change.

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.

Very large projects. A single query considers a bounded number of memories, favouring the most recent. Keep projects scoped by domain — see Large projects.

Empty query is a legitimate call. ?limit=5 with no query ranks on context signals alone — 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.

Retrieval · Ranking
Context selection