Glossary

The terms Workstate uses, in alphabetical order. Each links to the page that explains it.

A

Account: your organisation's Workstate account, or your own. It holds the people who use it, and their namespaces and sources. See Permissions.

Admin: a role that can add and change sources, create and delete namespaces, invite people, give them namespaces, and revoke their keys. See Permissions.

Agent: software that uses an AI model to act on a person's behalf, such as Claude Code, Cursor or an agent you build. Workstate is not an agent: agents use it. See Connect your agent.

Agent label: the name recorded with each ledger entry for the agent that wrote it. It comes from the call itself, so it is self-reported. See Keys & attribution.

API: the HTTP API that the console uses. API keys work with it too, and a public reference is coming. See Your own agent.

API key: a secret that lets an agent act as one person. It starts with rgc_live_, is shown once, and reaches every namespace its owner can reach. See Keys & attribution.

Append: to add an entry to a ledger topic's history, with ledger_append. Appending is the only way a topic changes. See The ledger.

Archive: to hide a ledger topic from search without deleting it, with ledger_archive. An archived topic stays readable by its id, and can be restored. See The ledger.

Attribution: the record of who wrote a ledger entry, meaning the person whose key was used, and with which agent. See Keys & attribution.

C

Chunk: a passage of a file. Workstate indexes chunks, and search returns them. See Search & citations.

Citation: where a result came from: the repository, file path and line range, or the ledger topic id. See Search & citations.

Code: the corpus that holds all GitHub files and uploaded code files. See Search & citations.

Console: the web app where people search, read the ledger, and manage sources, keys, the team and namespaces. See How Workstate works.

Corpus: one of the three parts of a namespace's index: code, wiki or ledger. Search can filter by corpus. See Search & citations.

Current state: where a ledger topic stands now. It changes only when an entry is appended. See The ledger.

D

Decision: a ledger topic type for a deliberate choice, its reasons and the alternatives rejected. A new decision starts as Proposed. See The ledger.

Default branch: the branch Workstate reads from each GitHub repository, at its latest commit. See Sources & sync.

Defect: a ledger topic type for a bug caught during development, and its fix. See The ledger.

E

Embedding: a list of numbers that represents the meaning of a passage or a question. Search compares embeddings to find passages by meaning. See How Workstate works.

G

GitHub App: the Workstate GitHub App, which reads the repositories you choose and nothing else. It is separate from signing in with GitHub, which gives Workstate no access to your repositories. See GitHub.

Grant: one person's access to one namespace. A namespace is granted when it is created (to its creator and to the account's owners and admins), when an invitation includes it, or later by an owner or admin on the Team page. See Namespaces.

H

History: the append-only list of entries on a ledger topic, each with its author, agent label and time. See The ledger.

I

Incident: a ledger topic type for a failure in a live system or service, and its root cause. See The ledger.

Index: the searchable store of chunks and ledger entries, kept for each namespace. See How Workstate works.

Investigation: a ledger topic type for exploration whose value is the finding, even when nothing changes. See The ledger.

Invitation: how people join an account. Sign-up is invite-only. An invitation names an email address, which the person must have verified on GitHub, their role, and the namespaces they will reach. See Team & invites.

L

Ledger: a namespace's append-only record of decisions, incidents, defects and investigations. See The ledger.

M

MCP (Model Context Protocol): the open standard that AI tools use to connect to outside tools and data. Agents reach Workstate over MCP. See Connect your agent.

MCP server: a service that offers tools to agents. Workstate has two: rag-corpus for search and rag-ledger for the ledger. See MCP tools.

Member: the role that can search, read the ledger, use Sync now and manage their own keys. See Permissions.

Move: to refile a ledger topic under another project, with ledger_move. The topic gets a new id, and the old id points to it. See The ledger.

N

Namespace: a separate index inside an account, with its own sources, search results and ledger. See Namespaces.

Namespace id: the id that agents use to name a namespace: ws- followed by 32 hexadecimal characters. See Namespaces.

O

Owner: the role of the first person in a new account. An owner can do everything an admin can, and only an owner can change another owner's access or keys. See Permissions.

P

Personal: the namespace that a new account starts with. See Namespaces.

Project: the name a ledger topic is filed under, usually a repository or a team. It forms the start of the topic id. See The ledger.

Provenance: the details that say where a search result came from. See Citation, and Search & citations.

R

Repository: what the repo search filter matches. For GitHub, it is the repository's name. For an upload, Confluence or Jira source, it is the source's name in lower case, with hyphens for spaces. See Search & citations.

Rerank: the second stage of search, in which a model reads the question with each candidate and orders the candidates by how well they answer it. See Search & citations.

Role: what a person can change in an account: Owner, Admin or Member. See Permissions.

S

Seat: a person's place in an account, with a role. See Team & invites.

Session: a console sign-in with GitHub. It lasts 7 days. See Keys & attribution.

Source: a place Workstate reads from: GitHub, Confluence, Jira or uploaded files. Each source belongs to one namespace. See Sources & sync.

Status (ledger): where a ledger topic is in its life: Open, Proposed, Accepted, Resolved, Superseded, Reverted or Won’t fix. See The ledger.

Status (sync): where a source's sync is: Queued, Syncing, Up to date, Failed, Paused, Stopping or Deleting. See Sources & sync.

Summary: the original framing of a ledger topic, fixed when the topic is opened. See The ledger.

Supersede: to replace an older ledger topic with a newer one. Workstate links the two and marks the older one Superseded. See The ledger.

Sync: one pass in which Workstate reads a source and updates the index. See Sources & sync.

Sync interval: how often a source syncs by itself: once a day unless an admin changes it, and never more often than every 5 minutes. See Sync schedules.

T

Tool: an action that an agent can call on an MCP server, such as search_corpus or ledger_create. See MCP tools.

Topic: one record in the ledger, covering one decision or one finding. See The ledger.

Topic id: a topic's id: its project, a hyphen and a number, such as payments-0012. See The ledger.

U

Upload source: a source whose content is the files you upload in the console. The API calls this kind of source disk. See Upload files.

W

Wiki: the corpus that holds documents: Confluence pages, Jira issues, and uploaded files that are not code. See Search & citations.

Workspace: the API's name for a namespace. See Namespaces.

X

X-RAG-Agent: an optional request header that labels the agent making the request. See Keys & attribution.

X-RAG-Namespace: an optional request header that names the namespace a request is for. See Namespaces.