Core concepts¶

Six objects. Everything in the API is one of them, or an operation on one.

flowchart TB
  ORG["Organization<br/><i>billing + isolation boundary</i>"]
  PRJ["Project<br/><i>namespace, e.g. billing-service</i>"]
  MEM["Memory / Context<br/><i>one typed statement</i>"]
  EMB["Embedding<br/><i>vector, computed at write</i>"]
  VER["Version<br/><i>snapshot per edit</i>"]
  SEL["Selected context<br/><i>ranked result of a query</i>"]

  ORG --> PRJ --> MEM
  MEM --> EMB
  MEM --> VER
  MEM -.->|"ranked by a query"| SEL

Organization¶

The tenancy and billing boundary. Created by POST /api/auth/register. Every API key belongs to exactly one organization, and every read is scoped to it — first in the SQL query, then re-verified per candidate before results are assembled.

Project¶

A namespace inside an organization, addressed by a client-chosen key you pass as project_id — "billing-service", "support-bot", whatever you like. Writing to a project key that does not exist creates it; reading from one that does not exist is a 404.

The project key is a contract

Deployed agents carry their project key hard-coded. PATCH /api/projects/{id} deliberately refuses to rename it — you can change the display name and description, never the key.

Memory (a.k.a. Context)¶

One statement an agent wants to survive the session. The API uses both words for the same object: POST /api/memory and POST /api/context are the same handler, and stored rows are called contexts.

Every memory has a type, and the type is validated — an unknown type is a 422, never a silent coercion:

Type	For
`fact`	Something that is true about the system
`decision`	A choice that was made, ideally with its reason
`preference`	A soft rule the team or user wants respected
`event`	Something that happened at a point in time
`constraint`	A hard rule that must not be violated
`relationship`	A link between two entities

Plus importance (0–1, your call) and confidence (0–1), free-form metadata, and an agent_id recording who wrote it.

→ Context · Memory

Embedding¶

A fixed-length float vector derived from the memory's content, computed once at write time and stored alongside it. Two providers exist and they are not equivalent — the default is not semantic. Read Embeddings before you design around this.

Version¶

Editing a memory's content creates a version entry. GET /api/context/{id}/versions lists them; POST /api/context/{id}/restore rolls back to one. Editing also recomputes the embedding, so an edited memory ranks on its new text.

→ Persistence

Selected context¶

The output of GET /api/context/{project}/relevant?query=…&limit=N: at most N memories, each carrying score, similarity and justification.

This is the object your prompt is built from, and it is the one thing Venkai exists to produce. The distinction between retrieval (finding candidates) and context selection (deciding what actually ships) is the subject of its own page: Context selection.