What is Venkai?

Venkai is a persistent context layer for AI agents. It is an HTTP service (plus a Python SDK and an MCP server) that does two things:

1. Store what an agent learns — as typed, scoped, versioned records.
2. Return the relevant subset of that store for a given query, ranked, with a per-item score and a justification.

Everything else in the product exists to support those two operations.

The one-sentence version

Venkai remembers what your agents decided, and hands back only the part that matters for the next task.

Where it sits

flowchart TB
  subgraph yours["Your system"]
    AF["Agent framework<br/>(LangGraph, CrewAI, custom loop…)"]
    LLM["LLM<br/>(Claude, GPT, local…)"]
  end
  subgraph vk["Venkai"]
    API["REST API"]
    RANK["Ranking policy"]
    DB[("Postgres / SQLite")]
  end
  AF -->|"write: what I learned"| API
  AF -->|"read: what do I need for X?"| API
  API --> RANK --> DB
  RANK -->|"top-N + justification"| AF
  AF -->|"prompt incl. selected context"| LLM

Venkai never talks to your LLM. It never decides what your agent does next. It is called by your code, on your terms, at the two moments you choose.

What it is not

Not a…	Why the distinction matters
LLM	Venkai generates nothing. GET .../relevant is a database query plus arithmetic — no model call, no token cost, no non-determinism.
Agent framework	There is no planner, no tool router, no execution loop. Bring your own; Venkai is a dependency, not a host.
Vector database	A vector DB returns nearest neighbours. Venkai returns a decision about what belongs in a prompt — similarity is 40 % of that decision (see Ranking).
Prompt / KV cache	A cache is keyed on an input and expires. Venkai's records are typed, editable, versioned, org-scoped and outlive any single prompt.
RAG over your documents	Venkai stores what agents write, not a corpus you ingest. There is no chunker, no document loader, no crawler.

What is actually implemented today

Beta API version 0.1.0, served from https://api.venkai.fr.

Capability	Status
Store typed memories (fact, decision, preference, event, constraint, relationship)	Stable
Ranked retrieval with score + justification	Stable
Project scoping and organization isolation	Stable
API-key auth (vk_live_… / vk_test_…)	Stable
Context versioning and restore	Beta
Python SDK	Beta
MCP server (15 tools)	Beta
Semantic embeddings (sentence-transformers)	Beta — opt-in, see Embeddings
Hashing embeddings	Stable — the default, and not semantic; read Embeddings before relying on it
Security graph analysis (/api/security/analyze)	Experimental
Agent handoffs (/api/handoffs)	Experimental
Published benchmarks	Planned — see Evaluation
pgvector / ANN index	Planned — candidates are scored in Python today

Next

• Why Venkai? — the problem, and the alternatives you should consider first.
• Quickstart — five minutes, real output.