Getting started
Concepts and limits
The vocabulary the whole product uses, in one place. Read this once and the CLI output, the API responses and the MCP tool results all say something you recognise.
Document base
A document base is a set of documents compiled into resident memory and served as one expert. It is the unit of everything: you load documents into it, you ask it questions, you expose it over MCP, and your plan counts documents per workspace across the bases in it.
Every base has a name and an id. Both work everywhere a base is named, in the CLI and in the MCP tools, so engram status "Support KB" and engram status c-8f2a... do the same thing. Names are matched exactly first, then case-insensitively. Two bases with the same name is the one case where you have to use the id, and the error names the candidates so you can copy one.
A base carries a status through its life:
| Status | Means |
|---|---|
new | Created, not yet onboarded. Documents can be added. |
training | Onboarding is running. Documents that are already ready can be queried. |
ready | At least one document is servable, and questions are answered from resident memory. |
failed | The last onboarding run produced nothing servable. The error says why. |
Alongside status there is an onboarding step, which is the wizard's cursor rather than the base's health: name, documents, model, review, onboarding, ready. It is what makes the wizard resumable.
What counts as a document
A document is a unit of text, not a file:
A document is up to 4,000 tokens of extracted text, roughly six pages. A longer file counts as several, so a sixty-page report counts as ten documents. Adding files is always free. You pay to keep them ready to answer from, not to load them.
Files are read into that text first. The platform parses .txt, .md, .pdf, .docx, .doc, .html, .htm, .xlsx, .xls, .csv and .tsv, and it publishes that list, so the CLI asks the server what it can read rather than guessing. Empty files are skipped everywhere, on upload and on push.
A document's identity is its path inside the base. Upserting the same path twice replaces the document rather than adding a second copy, which is what makes engram push and add_document safe to re-run. A long file that was split into sections stays one document in every listing, with a section count attached, and its single id still pins the whole file.
Document lifecycle
Each document walks its own states, independently of the base. This is what engram docs list and engram status <base> group by:
| State | Means |
|---|---|
pending | Registered, nothing done to it yet. |
parsing / parsed | Text is being extracted, then extracted. |
queued / building | Waiting for the build, then being compiled into a cartridge. |
ready | Answerable. It appears in MCP listings and can be cited as a source. |
failed | Parsing or building failed. The reason travels with the row. |
stale | The content changed and the new cartridge is not built yet. Still servable from the old one. |
Only ready documents are listed to an MCP client, because an id it cannot pin is worse than a shorter list. The CLI groups a base's documents by lifecycle, which is the quickest read on where a load got to:
engram docs list "Support KB" --limit 20
engram status "Support KB" --json | jq '.documents'Jobs and sync runs
Onboarding runs as a job. The one you watch is the corpus-level aggregate of kind train; underneath it, each batch of documents is a build job. Both carry a status of running, succeeded, failed or canceled, plus progress and an estimate while they run.
A sync run is the other half: one pass of loading documents into a base, whether that came from engram push, a registered bucket, or a scheduled pull. It carries its own state and document counters, which is how you answer "is my load still landing":
engram status "Support KB" # latest sync run and latest job
engram sync runs --corpus "Support KB" # the historySync-run states are succeeded, failed, limited, canceled and error. limited is the one worth knowing: the run stopped against a plan allowance rather than a bug.
Credentials and scopes
One credential covers all of it: the workspace API key.
| Credential | Covers | Scopes |
|---|---|---|
Workspace API key (ek_...) | Every document base in the workspace, over REST, the CLI, and MCP | ingest, query, admin |
engram keys create --name "claude-desktop" --scope query
engram keys create --name ci --scope query --scope ingest --expires 2026-12-31T00:00:00Z
engram keys listScopes are what a key is allowed to do: query asks questions, ingest loads documents, admin manages the workspace. Create keys on the API keys page in the app or with engram keys create; the secret is shown once and never again. Because it is one credential everywhere, revoking a key cuts off the CLI, your integrations and every connected assistant at the same moment. See API keys and scopes.
What your plan gates
Five things are capped per workspace: documents kept ready, queries per month, seats, document bases, and ingest per day. The numbers, and what happens when you pass one, live on plans and allowances, which is the single source of truth for them.
Two behaviours are worth knowing here because they show up as errors rather than as numbers. A free tier hard-stops at its allowance: it cannot run up a bill. A paid plan with an active subscription is allowed past its included allowance and the overage is metered. And a workspace whose card has failed goes read-only rather than dark, so queries keep working while writes stop.
Buying any plan requires accepting the Service Agreement and the DPA in Settings > Legal first. Both are industry-standard Common Paper agreements with an Engram cover page, and your acceptance receipt quotes the exact version you agreed to.