Skip to content

Your first retrieval

There are two read endpoints and they do very different things. Picking the wrong one is the most common integration mistake.

Endpoint Returns Use it for
GET /api/context/{project} Everything, paginated, newest first, optional q/type/agent filters Dashboards, audit, export
GET /api/context/{project}/relevant Top-N ranked for a query, with scores Building a prompt

If you are putting memory into an LLM prompt, you want /relevant.

Ranked retrieval

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=3'

memories = client.memory.recall("which database did we pick", limit=3)
for m in memories:
    print(round(m["score"], 3), m["type"], m["content"])

venkai_recall(query="which database did we pick", project="billing-service", limit=3)

Response:

{
  "project_id": "billing-service",
  "query": "which database did we pick",
  "memories": [
    {
      "id": "ctx_cc55e4a7bbc5",
      "type": "decision",
      "content": "We use Postgres, not MongoDB, because the ranking query needs joins.",
      "importance": 0.9,
      "access_count": 0,
      "created_at": 1787007131.3763673,
      "metadata": {"ticket": "ARCH-14"},
      "score": 0.4789,
      "similarity": 0.1348,
      "justification": "relevance 0.13 to the query"
    }
  ]
}

Reading the three ranking fields

Field Meaning
similarity Relevance of this memory to the query, 0–1.
score The overall ranking value, 0–1 — relevance combined with context signals. Results are sorted by it.
justification Human-readable explanation of the result. Informational; do not parse it.

Why similarity can look low

In the example above, 0.13 for a clearly on-topic memory looks wrong. It is expected today: relevance currently favours shared wording over paraphrase, and "database" and "Postgres" share none.

The memory still ranked first because it is recent and was written with a high importance. That is the ranking doing its job — and a reason to write memory content with the terms your agents will query with. See how relevance behaves today.

Retrieval with no query

Omit query and ranking relies on context signals alone — importance, recency and usage:

curl -sG https://api.venkai.fr/api/context/billing-service/relevant \
  -H "Authorization: Bearer $VENKAI_API_KEY" --data-urlencode 'limit=5'

That is a useful "what matters in this project right now" call.

Choosing limit

limit is your context budget. There is no server-side token cap and no truncation: ask for 50, you get up to 50 whole memories.

limit Reasonable for
3–5 A focused sub-task, a tool call
5–10 A planning step at the top of a run
20+ Analysis or export, not a prompt

Filtering instead of ranking

For "show me every decision", use the list endpoint — it is not ranked, and that is what you want for an audit view:

curl -s "https://api.venkai.fr/api/context/billing-service?type=decision&limit=50" \
  -H "Authorization: Bearer $VENKAI_API_KEY"

Query parameters: type, q (substring match), agent, order (created_desc by default), limit (capped at 200), offset.

Next: Add Venkai to an agent.