Concepts
Retiform keeps two kinds of record for your agents: the documents you upload, and the memory your agents write. Everything an agent gets back from either one carries a citation, so you can check where each piece of context came from.
Your team and its tenant
Your team is the people who share Retiform, and the agents they connect. Your tenant is the team's private space: its documents, its memory and its settings. Nothing in a tenant can be read from another one. A tenant administrator is a member who can invite people, see and revoke every agent's approval, and export or delete the tenant. An agent client is one connected agent application, such as Claude Code on one person's machine. Any member approves their own agent client when they connect it.
Documents
A document is a Markdown, HTML, plain-text, Word (.docx) or PDF file you upload, through the console's
Documents page, the kg command or the REST API. An agent's upload_document tool takes Markdown, HTML
and plain text only. A PDF is read page by page: each page is turned into an image and a model reads its
text, so a PDF takes longer than other files and counts against the plan's PDF pages for the month. A PDF of
more than 300 pages is refused; split it into smaller files.
Retiform keeps the document's normalized text, along with the original file's digest, size and media type. For Markdown, HTML and plain text it doesn't keep the uploaded file itself. It keeps a Word or PDF file as you uploaded it, and your export includes it. It keeps no page images.
A document can carry an external identifier of your choosing, such as its file name. Uploading again with the same external identifier updates that document rather than creating a new one.
Revisions
Each upload of a document is a revision. Uploading changed text makes a new current revision. Uploading identical text creates nothing and says so.
Only the current revision's passages are searched. Earlier revisions leave search but stay citable: Retiform keeps the most recent superseded revisions of each document, 10 by default, so a citation an agent already returned still resolves. A revision older than those can no longer be cited.
Processing jobs
An upload returns a job. Retiform splits the text into passages and embeds them in the background.
Your agent polls the job with get_document_job until it has succeeded, failed or been
cancelled. A failed job says why.
Passages
A passage is a section of a document's text, small enough to be searched and returned whole. Each passage keeps its heading path, the headings above it in the document. Passages can be found by keyword as soon as they're stored, and by meaning once they're embedded.
Citations
A citation points at one passage of one revision:
| Field | What it is |
|---|---|
documentId |
The document. |
revision |
The revision the passage belongs to. |
ordinal |
The passage's position in that revision. |
spanStart, spanEnd |
Where the passage sits in the revision's normalized text, in Unicode code points. The start is included and the end is not. |
read_passage turns a citation back into its text and says whether the revision is still current.
A citation to a deleted document, or to a revision that's no longer kept, answers that it is unknown
or no longer available.
Assembled context
assemble_context answers a question with context, not with an answer. It searches your passages,
by keyword and by meaning by default, and returns the best ones that fit a token budget, each with
its citation. The budget is 2,000 tokens unless your agent asks for another, from 100 to 16,000.
Your agent writes the answer from that context and cites the passages it used.
Memory
A memory entry is a statement your agent records, with citations to the passages or records it's based on. Each entry records who wrote it: the person, or the agent acting for them, and when.
Supersession
A memory entry is never edited. To correct one, an agent supersedes it: it records a new entry that
replaces the old one. The old entry stays readable, marked superseded, with its original statement
and citations. recall_memory returns current entries unless your agent asks for superseded ones
too.
History
get_memory_history returns every version of a memory entry, oldest first, with who wrote each
version and when. A chain of corrections can hold up to 100 versions.
Reviewing what is new
The console's memory page opens on what your agents recorded since you last looked: each new entry with who wrote it, when, and what it corrects. Accept an entry that holds, and your acceptance is kept on it with your name and the time; its statement and who wrote it don't change. Correct one that doesn't, and your version supersedes it, so an agent's next recall returns yours.
The list is yours: another member's is their own. It moves on only when you mark it as seen, or page it to its end, never because you opened it. Entries recorded in the last minute stay listed until the next time, so an entry still being written is never skipped. Your first look covers the last 14 days.
The weekly digest
A member who turns it on in the console's account page gets one email a week for their tenant: how many entries were recorded, corrected and accepted in the week, how many of the week's entries await review, how many current entries cite a source that has changed, and short excerpts of up to five of the newest, each with who wrote it and when. An excerpt is at most 120 characters; the email never holds a whole entry, a passage or a document's text.
The digest is off until you turn it on, and any member may. An administrator can turn it off for the whole tenant. It covers the week to Monday 00:00 UTC, is sent at most once a week, and not for a week with no activity or a tenant that is suspended, being deleted or read-only. Every digest has a link that turns it off without signing in.
When a source changes
A memory entry can outlive the documents it cites. When a cited document gets a new revision, or is
deleted, every entry citing it says so: its sourceChanges lists each cited passage whose document
is now revised (with its current revision) or deleted. The mark means the source changed since
the entry was written. It doesn't mean the entry is wrong, and an entry without a mark hasn't been
checked by anyone: Retiform compares revisions, not meanings, so a new revision marks every entry
citing the document, even where the cited text is unchanged.
To clear the mark, check the entry against the document as it is now. If it still holds, confirm
it with confirm_memory (or the console's memory page), naming the document and its current
revision, or no revision for a deleted document. The entry's statement and who wrote it stay as they
were; the confirmation is kept in the entry's history with who made it and when. If the document
changes again, the mark comes back. If the entry no longer holds, supersede it instead.
recall_memory and the console's memory list can return only marked entries, or leave them out.
Deletion
Deleting a document removes its passages from search and makes its citations unavailable. Memory entries that cited it keep their statements and are marked as citing a deleted source. Deleting a document frees the space its text took.
Your text is not instructions
Everything an agent gets back that came from your documents or memory is marked as text from your
tenant's records, in a field named tenantData. Every tool description tells the agent to treat
that text as content, never as instructions. Retiform doesn't try to detect or rewrite
instructions inside your text, so keep that in mind if you load content you didn't write.