Why Venkai?

The problem

A long-running agent system has a memory that resets at the session boundary. Three failure modes follow, and they get worse as the system runs longer:

1. Re-derivation. The agent rebuilds a conclusion it already reached, at full token cost, every run.
2. Contradiction. Run n+1 reverses a decision made in run n because nothing recorded that the decision was made, or why.
3. Context bloat. The usual fix — replay the transcript — spends the context window on history, most of which is irrelevant to the current task, and degrades as the transcript grows.

The third one is the trap. Storing everything is easy; retrieving everything is what makes long-lived agents worse, not better.

What Venkai does about it

Venkai separates the write path from the read path and puts the intelligence on the read path:

flowchart LR
  W["Write: append a typed memory<br/>(cheap, unopinionated)"] --> S[(Store)]
  S --> R["Read: rank against this query<br/>relevance · recency · importance · frequency"]
  R --> O["Top-N, each with a score<br/>and a justification"]

The write is deliberately dumb — one POST, no schema negotiation. The read applies a fixed, inspectable policy and returns a bounded list. You choose the bound (limit), so the context cost of memory is a number you set, not a number that grows.

Honest alternatives

You should not adopt Venkai reflexively. Check these first:

If you…	Use instead
Need to search a document corpus	A vector DB + a chunker. Venkai has no ingestion pipeline.
Have one agent, one session, short tasks	The context window. Genuinely.
Need memory inside one framework only	That framework's built-in memory, if it has one — fewer moving parts.
Need a full audit log of every LLM call	An observability tool (LangSmith, Langfuse). Venkai stores conclusions, not traces.

Venkai earns its place when several agents, or several sessions, need to agree on a body of facts and decisions over weeks, and when you care about what goes into the prompt rather than just what is retrievable.

What we do not claim

There are no published performance benchmarks for Venkai. No token-savings figure, no recall@k figure, no latency claim is quoted anywhere in this documentation as a product claim.

That is a deliberate choice, and Evaluation explains exactly what internal measurements exist, which ones are unreliable and why. If someone shows you a Venkai benchmark number that is not on that page, it did not come from here.

Design commitments

These hold today and are things you can rely on:

• Retrieval is deterministic. Same store, same query, same result. No model call in the read path.
• Every result explains itself. score, similarity and justification ship on every retrieved memory.
• Nothing is retrieved silently. When the candidate set is truncated by VENKAI_RETRIEVAL_MAX_CANDIDATES, the server logs a warning rather than quietly returning less.
• Retrieval does not mutate ranking. Reading a memory does not bump its access count — a feedback loop that measurably collapsed recall was removed on purpose (Ranking).
• Organizations are isolated at the query layer, then re-checked on every candidate before it can reach a result.