Core concepts¶

Five 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>"]
  VER["Version<br/><i>snapshot per edit</i>"]
  SEL["Selected context<br/><i>ranked result of a query</i>"]

  ORG --> PRJ --> MEM
  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 and write is scoped to it.

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 behave identically, and stored records 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

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. An edited memory is retrieved on its new text immediately.

→ 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.