Venkai¶

Venkai is a persistent context layer for AI agents. Agents write down facts, decisions, preferences, events, constraints and relationships; Venkai keeps them across sessions, models and workflows, and hands back a ranked short list when the next agent asks for context.

Beta — API version 0.1.0, live at https://api.venkai.fr. See Status & maturity.

What problem does it solve?¶

An agent session ends and its reasoning evaporates. The next run re-derives the same constraints, re-asks the same questions, or contradicts a decision made yesterday. The usual patch — paste the whole history back into the prompt — buys continuity by spending the context window on text the model does not need.

Venkai splits those two things apart:

	Storage	What Venkai adds
Write	Append a memory with a type, an importance and metadata	Embedded and persisted at write time
Read	Return everything	Return a ranked short list for a specific query

The read side is the product. GET /api/context/{project}/relevant?query=…&limit=5 returns at most limit memories, each with a score and a justification.

How does it work?¶

flowchart LR
  A[Agent] -->|POST /api/memory| B[Venkai API]
  B --> C[(Postgres)]
  B --> D[Embedding provider]
  D --> C
  A -->|GET .../relevant?query| B
  B --> E[Candidate set]
  E --> F[Score: relevance · recency · importance · frequency]
  F --> G[Top-N + justification]
  G --> A

Every memory is embedded once when written and stored alongside its content. At retrieval, the query is embedded, compared to candidates by cosine similarity, and blended with three non-semantic signals. Details in Retrieval and Ranking.

How do I integrate it?¶

Three surfaces, one API behind all of them:

REST API — Authorization: Bearer vk_live_…, any language.
Python SDK — client.memory.remember(...) / client.memory.recall(...).
MCP server — 15 tools for Claude Code and any MCP-compatible client.

Start with the Quickstart — five minutes from an API key to a ranked retrieval.

Why is it different?¶

Venkai is deliberately not several things it is often mistaken for:

It is not	Because
An LLM	Venkai does not generate text. It never calls a model to answer.
An agent framework	No planning loop, no tool routing. It sits beside your framework.
A vector database	It ships a scoring policy, not just a nearest-neighbour index.
A prompt cache	Memories are typed, editable, versioned and org-scoped, not keyed on a prompt hash.

The closest honest description: the memory a vector store does not have an opinion about, plus the ranking policy that decides what actually goes into the prompt.

Status and maturity¶

Venkai is pre-1.0. This documentation labels every capability:

Label	Meaning
Stable	Implemented, covered by tests, running in production
Beta	Implemented and running, API may still change
Experimental	Implemented but not validated; do not build on it
Planned	Not implemented. Documented so you can tell it apart from the rest.

There are no published performance benchmarks for Venkai yet. What exists internally, and why it is not quoted as a claim, is written out in Evaluation. If you are evaluating Venkai and need numbers, read that page first — it is the honest one.