Skip to content

How Venkai works

Venkai sits beside your agent, not inside it. Your code calls it at two moments: when the agent has learned something worth keeping, and when it needs context for a task.

flowchart TB
  subgraph clients["Your side"]
    AG["Agent / application"]
    SDK["REST · Python SDK · MCP"]
  end
  subgraph venkai["Venkai"]
    API["Venkai API"]
    STORE[("Persistent context<br/>scoped to your organization")]
    RANK["Retrieval &amp; ranking"]
  end
  AG --> SDK --> API
  API -->|store| STORE
  API -->|ask| RANK
  STORE --> RANK
  RANK -->|ranked context| API

Storing context

POST /api/memory with a project key, a type, some content and an importance.

  • The type is validated against the six memory types; anything else is a 422.
  • The project is created on first write if it does not exist.
  • The write is synchronous: once you get a 200, the memory is persisted and immediately retrievable.

Asking for context

GET /api/context/{project}/relevant?query=…&limit=N

  1. Venkai looks at the memories of that project, within your organization only.
  2. It evaluates each one against your query, combining semantic relevance with additional context signals — how recent the memory is, how important you said it was, and how it has been used.
  3. It returns at most N memories, best first, each with a score, a similarity and a human-readable justification.

Retrieval does not call a language model and does not modify stored memories.

Implementation may evolve

The retrieval and ranking implementation is internal and improves over time. The public API — endpoints, fields, types and the meaning of limit — is the contract, and changes to it are versioned.

Guarantees you can rely on

  • Organization isolation. An API key only ever reads and writes its own organization's data.
  • Bounded output. limit caps what comes back. The context cost of memory is a number you choose.
  • Explained results. Every retrieved memory carries a score and a justification.
  • Reads do not rewrite history. Retrieval leaves stored memories untouched; edits are explicit and versioned.

Next