Skip to content

Operations reference

An operation (op) is one named unit of work on the Loom wire, such as memory.set or code.search. Each op is declared once, in the operation registry. The HTTP route, the MCP tool, the OpenAPI document, the capability catalogue and both SDKs' op tables are derived from that declaration. The table at the end of this page is generated from the same registry.

The registry

Each op is an Operation (server/operations/base.py) in a group module's OPERATIONS list, an ops*.py module in its domain's api/ package (server/memory/api/ops_memory.py, server/code/api/ops.py). server/operations/registry.py joins the groups in _OPERATION_MODULES into ALL_OPERATIONS, which the transports iterate. An Operation carries:

Field Meaning
name Dotted <group>.<verb>. The group is the text before the first dot.
input_model, output_model Pydantic models: the request body and the 200 response.
handler The async function that runs the op, in its domain's app/ package (server/<domain>/app/).
required_role The minimum role the caller's token must hold on the namespace.
idempotent Safe to retry. Idempotent ops accept an idempotency key; see HTTP API.
audit A successful call writes a row to loom.audit_log.
writes Set on the few viewer-callable, idempotent ops that still change stored state (a feedback row, a watch), so they are not read-only.
maturity stable or experimental. It decides the MCP all listing, and op_reach_census.py --check fails a stable op nothing reaches.
budget_p99_ms, shape_budgets_p99_ms The target p99 latency, overall and per request shape. A successful call over budget emits a budget.violated event.
skip_namespace_authz The op acts on a namespace (join, leave, register) rather than in one, or its target is one only the handler can resolve (an id, an erasure scope); the handler enforces its own rules. The role check still runs.
deployment_scoped The op reads facts about the deployment (build, registry), not tenant data; a namespace-scoped token passes with its best role.
row_scoped The op is addressed by an org-wide id (memory_id, erasure_id, pattern_id). The handler authorizes the row's scope and hides a foreign row (row-scoped operations).

Adding an operation walks through declaring one.

Names and addresses

One op has one name and one address per surface:

Surface Address Example
HTTP POST /v1/<name> (Operation.http_path) POST /v1/memory.set
MCP the tool loom_ + the name with dots as underscores (Operation.mcp_tool_name) loom_memory_set
Python SDK a group-client method, or await agent.call("<name>", {...}) await bot.memory.set(...)
TypeScript client.call("<name>", input) or the camel-cased group accessor client.memory.bulkSet(...)

The ledger (loom.agent_events), the audit log and the latency budgets record the dotted name, so a GROUP BY operation lines up with this page.

Reading the table

  • Operation is the dotted name.
  • Summary is the first sentence of the input model's docstring, else of the op's MCP description (server/transport/mcp_descriptions.py), else of the handler's docstring. The full contract is the schema.
  • Role is the minimum role: viewer < writer < admin < org_admin < platform_admin (Role in server/operations/base.py). org_admin and platform_admin are covered in Tokens and grants.
  • Kind is one of:
    • read: Operation.read_only is true (idempotent, viewer, not audited, not writes). MCP sets readOnlyHint only on these, and the readonly toolset lists only these.
    • idempotent: changes state; a retry with the same input is safe.
    • write: a state transition; a blind retry can apply it twice unless the op takes a content-hash precondition (if_match_sha256).
  • Listed under all is yes when an MCP connection on the all toolset lists the op.
  • Audit is yes when a successful call leaves an audit_log row.

MCP all listing

LOOM_MCP_TOOLSET=all (or ?toolset=all) lists every op that is not hidden from MCP and is either stable or on the core or atomic roster (listed_under_all in server/operations/toolsets.py). The code.* ops also need LOOM_MCP_CODE_TOOLS=true.

An op left out of that listing behaves like any other op: it is served at POST /v1/<op> and from both SDKs, and, unless MCP hides it, callable by name over MCP or through loom_op. Role checks, rate limits, audit and serving do not depend on maturity.

The label is set by hand in the op's declaration. The reach census (scripts/codegen/op_reach_census.py, gated by tests/unit/test_op_reach_census.py) reports each op's reach and, with --call-counts, its calls; it never rewrites the declaration, and its --check (in make lint) fails a stable op hidden from MCP that nothing else reaches.

Toolsets

A toolset decides which ops an MCP connection lists in tools/list, never what it can call. The rosters, the synthetic tools and what hidden ops answer are in MCP toolsets. ops.capabilities reports each op's toolsets.

Schemas

The table gives a summary. The exact fields come from the op's Pydantic models:

Source Gives
GET /v1/api/openapi.json (no token) The full input and output JSON Schema of every op, for code generation.
POST /v1/ops.capabilities (any token) Per op: request_fields, response_fields, role, budget, idempotency, audit, mcp_tier, toolsets, plus build_commit.
loom export-actions --format json or --format cedar An MCP tools/list-shaped manifest with inputSchema, outputSchema and a loom block per tool, or a Cedar schema.
sdk/python/loom/ops.py, sdk/typescript/src/generated/ops.ts Generated per-op TypedDicts and TypeScript interfaces, plus the OPS spec table.

The MCP listing trims each schema: org and every field marked MCP_HIDDEN (server/operations/base.py) are left out, because every listed property costs tokens on every turn. A hidden field is still accepted by name. See Exporting the action schema for the manifest and Cedar output, and HTTP API for reading the catalogue at start-up.

How the table is generated

scripts/codegen/docs_reference.py imports ALL_OPERATIONS, groups ops by the text before the first dot, and rewrites the region between the markers below. make lint runs it with --check, so a registry change that does not regenerate this page fails CI. Edit the op's docstring or declaration, never the table.

Each group also has a generated field page, operations/<group>.md (for example operations/memory.md), with every input and output field's type, default and meaning. The meaning is the comment above the field in its Pydantic model.

python scripts/codegen/docs_reference.py          # rewrite the regions
python scripts/codegen/docs_reference.py --check  # exit 1 when a region is stale

Operations

361 operations in 42 groups. Every op is served at POST /v1/<op> and as the MCP tool loom_<op> (dots become underscores).

Columns: Role is the minimum role (viewer < writer < admin < org_admin < platform_admin); Kind is read (idempotent, viewer, unaudited, writes nothing — MCP readOnlyHint), idempotent (safe to retry) or write; Listed under all says whether an MCP connection on the all toolset lists the op in tools/list (code.* ops only with LOOM_MCP_CODE_TOOLS=true); an op marked no is still callable by name or through loom_op, unless it is hidden from MCP; Audit marks ops that leave an audit_log row.

Groups: admin · agents · assistant · audit · blacklist · calibration · code · collection · conflicts · consolidations · context · conversation · cost · decision · erasure · extraction_policy · facts · grants · help · inbox · insights · knowledge · learnings · memory · memory_schema · mentor · namespace · observe · ops · org · policy · procedure · profile · profile_schema · run · search · session · task · tracker · ui · webhook · working_memory

admin

Fields for every admin op: operations/admin.md.

Operation Summary Role Kind Listed under all Audit
admin.users Aggregate subjects from namespace_grants + namespaces.owner_email, join in last-active from the audit log, mark configured platform admins. org_admin idempotent no

agents

Fields for every agents op: operations/agents.md.

Operation Summary Role Kind Listed under all Audit
agents.connected The agents active in a window: last seen, operations and cost per agent. viewer read yes

assistant

Fields for every assistant op: operations/assistant.md.

Operation Summary Role Kind Listed under all Audit
assistant.ask Ask the Loom assistant one question about this namespace and get one cited answer: what it holds, how it is used, counts over its rows, and how to write it better. viewer write no

audit

Fields for every audit op: operations/audit.md.

Operation Summary Role Kind Listed under all Audit
audit.list Query the audit log (tamper-evident per-row hashes). viewer read no

blacklist

Fields for every blacklist op: operations/blacklist.md.

Operation Summary Role Kind Listed under all Audit
blacklist.add Refuse future memory writes whose value matches a pattern. writer idempotent yes yes
blacklist.list List patterns that suppress memory storage. viewer read no
blacklist.remove Remove a previously-added blacklist pattern. admin idempotent no yes
blacklist.sweep Tombstone the live rows an existing pattern matches. writer idempotent no yes

calibration

Fields for every calibration op: operations/calibration.md.

Operation Summary Role Kind Listed under all Audit
calibration.get Resolve the active calibration for (org, namespace): per-namespace, then cluster-wide, then scalar fallback, with the source tier reported. viewer read no

code

Fields for every code op: operations/code.md.

Operation Summary Role Kind Listed under all Audit
code.ask Ask a QUESTION about this codebase and get a grounded answer with [file:line] citations — 'how does TTL drop old rows', 'where is the memory limit enforced'. viewer read yes
code.backport_gap Which release branches still carry the bug this fix removed, and the exact PR to cherry-pick there? viewer read no
code.backport_gaps The set-wide backport report: which merged fixes labelled for backport does a release branch still owe? viewer read no
code.bisect_candidates Rank PRs that may have introduced a bug; Loom does not test or reproduce it. viewer read no
code.blame_range Which merged PRs last touched these lines, between release A and B? viewer read no
code.calibrate Derive code-specific abstention thresholds from the authored probe corpus (query/positive/hard-distractor triples over the indexed repo) and persist them as this namespace's calibration. admin write no yes
code.callees What does this symbol call — forward call edges (depth<=3), tier-marked like code.callers. viewer read no
code.callers Who calls this symbol — exact reverse call edges (depth<=3), compiler-resolved where available; edge_kinds: ['inherits'] narrows the walk to what implements or extends a type. viewer read yes
code.context_pack Briefing at the START of a task, instead of exploring file by file. viewer read yes
code.context_packs List the stored per-PR context packs of a repository, optionally for one PR. viewer read no
code.conventions The repository's recurring maintainer checks as facts over one PR's diff: a setting added or re-defaulted without a SettingsChangesHistory entry; the same setting's docs mention; a new… viewer read no
code.coverage Report how much of a repository the index covers at its head: per language, per tier, and the gaps. viewer read yes
code.coverage.unwatch Cancel a coverage watch on a commit. viewer idempotent no
code.coverage.watch Ask for a task-inbox message when the index covers a commit, instead of polling for it. viewer idempotent no
code.coverage_claim Is this already tested? viewer read no
code.enclosing Batched path:line -> enclosing function. viewer read yes
code.examples Real call sites of a symbol, ranked test-covered-first — a current, tested usage example beats the deprecated one grep finds first. viewer read no
code.files Which indexed files have this NAME — an rg-style glob (tests/queries/0_stateless/05138_*, /*Parquet*.cpp), a basename stem (05138_with_fill matches the stem exactly or as its leading prefix… viewer read no
code.first_build Which CI build first carried this commit? viewer read no
code.grep Exact-match lookup over the indexed corpus. viewer read yes
code.history The merged PRs that most recently touched a symbol or path: number, title, author, labels, and what reviewers said about that file — up to reviews_per_pr (default 3, 0 = none) human review comments… viewer read yes
code.impact Symbol-shaped (name/symbol_id) or diff-shaped (files/diff) blast radius. viewer read yes
code.index_errors List the files the code index failed to parse or ingest, with the error and the commit. viewer read yes
code.index_status Health of the code index: indexed head commit, compiler-tier commit, row counts, watermarks, and the weekly tables' state (symbol_stats_rows/at, unit_risk_rows/at; 0 = not written yet). viewer read yes
code.map PageRank-ordered orientation map of the indexed repository with per-file summary cards, token-budgeted. viewer read no
code.outcome Tell loom what you did with a code answer, by its trace_run_id: 'used_in_answer', 'opened_file' (targets = the paths), 'fell_back_grep' or 'ignored'. viewer idempotent no
code.outline "What is in this file?" — the question a whole-file read answers at the price of the whole file. viewer read yes
code.path_guards The conditions that stand on the call path from from_symbol to to_symbol: the verify(reaches) chain, and for each hop the guards the call site sits under inside its caller… viewer read no
code.pr_check A PR draft asks whether a PR like it already exists. viewer read no
code.recent_commits List the most recently indexed commits of a repository, decorated with subject and time from the clone. viewer read yes
code.refresh CI calls this right after a merge lands: run one ingest pass now instead of waiting for the poll interval. writer write no yes
code.reindex Operator repair: move the git watermark (e.g. back N commits after a bad pass, or to a specific sha). admin write no yes
code.repo.add Add a repository's branch as a new read-only index. viewer write yes yes
code.repo.add_branch Index another branch of a repository the caller maintains. admin write yes yes
code.repo.remote_branches What a Git remote shows before anything is written — every branch with its head, the default branch, the ones that look like release branches, and the ones indexed here already — so the add dialog… viewer read yes
code.repo.remove Retire a repository index a person added. admin idempotent yes yes
code.repo.set_access A maintainer sets a repository's access — its classification (standard | restricted) and join policy (open | approval | closed). admin idempotent no yes
code.repo.set_source A maintainer sets the trackers this repository reads (records of issues, PRs, tests and incidents registered with tracker.source.add), in order. admin idempotent no yes
code.repos Lists the code namespaces (repo@branch entries) configured on this deployment that the caller is authorized to read, across orgs — each row carries its org. viewer read yes
code.review_brief A merged PR's review brief: the point read of what the ingest built at merge — touched symbols with callers and fan-in, coverage verdicts, setting facts, regression history, blame of the deleted… viewer read no
code.scip_ingest Accept one part of a SCIP index upload (compiler-tier symbols and references) for a batch. writer idempotent no yes
code.scip_status Report the progress of a SCIP upload batch: parts received and apply status. viewer read no
code.search Search the shared code index of this repository (fresh to the last merged PR). viewer read yes
code.setting_facts One ClickHouse setting, the four places that define it: its declaration and tier (production / important / beta / experimental / obsolete), every default change with the release it shipped in… viewer read no
code.symbol Exact symbol lookup: definition, signature, doc comment, and body of a function/class/enum by (qualified) name — compiler-grade where available (tier='scip'), resolved across C++ overloads… viewer read yes
code.symbol_history The regression history of one function: the merged PRs that touched it (with linked issues, reverts, inline review comments inside its span), and — through the tracker namespace bound to this code… viewer read no
code.test_gate The pre-PR question in one call: for THIS change, which tests must run, and which touched code no test reaches. viewer read no
code.test_home Where does a new test case belong? viewer read no
code.tests_for Which stateless tests carry EVERY named facet: the tests that SET a setting, call a function, create an ENGINE, read a system.* table, use a FORMAT, carry a -- Tags: tag, or expect an error… viewer read no
code.trace Paste a stack trace / backtrace; get each frame resolved to its definition in one call — the incident-workflow entry point. viewer read yes
code.verify Verify one closed-form claim against the index and return a three-valued verdict. viewer read yes
code.verify_citations Every citation a draft carries, resolved against the index before the draft is posted somewhere public and irreversible. viewer read no

collection

Fields for every collection op: operations/collection.md.

Operation Summary Role Kind Listed under all Audit
collection.create Create a collection: a namespace read and written only through grants. viewer idempotent no yes
collection.delete Delete a collection with what it holds: a purging erasure of the namespace (documents, chunks, originals, memory leave the disk), then it leaves the directory and the tree, and its name is never used… admin idempotent no yes
collection.list List the collections the caller can read, by name. viewer read no
collection.move Put a collection under another one, or detach it. admin idempotent no yes

conflicts

Fields for every conflicts op: operations/conflicts.md.

Operation Summary Role Kind Listed under all Audit
conflicts.allowlist_list List (memory_key, memory_key) pairs marked as known-non-conflicting so the conflicts worker stops flagging them. viewer read no
conflicts.allowlist_remove Revoke an allow decision; the pair will re-flag on future writes. admin idempotent no yes
conflicts.list List unresolved conflicts where two memories contradict each other. viewer read no
conflicts.propose_revision Return non-destructive revise/contract/allow suggestions. viewer read no
conflicts.resolve Pick the winner of a conflict (keep A, keep B, keep both, merge). admin idempotent no yes

consolidations

Fields for every consolidations op: operations/consolidations.md.

Operation Summary Role Kind Listed under all Audit
consolidations.list Namespace-scoped consolidation-run history. agent + user_id are optional — runs aggregate across them when omitted. viewer read no

context

Fields for every context op: operations/context.md.

Operation Summary Role Kind Listed under all Audit
context.fetch Read back a parked result by key: a character slice (offset/limit) or only the lines matching a regex (pattern, with context_lines). viewer read no
context.offload Park a large tool result (log, page, diff, query output) outside the model context. writer idempotent no
context.pack A task's memories, decisions and procedures: call it first in each task, unless a Loom hook already put Loom's context in this session. viewer read yes

conversation

Fields for every conversation op: operations/conversation.md.

Operation Summary Role Kind Listed under all Audit
conversation.append Log one chat turn (role + content) to a thread. writer idempotent yes
conversation.compact Summarize old turns into one embedded system turn and tombstone the originals. writer idempotent no yes
conversation.create Open a thread container. writer idempotent no
conversation.delete Soft-delete one thread: its messages, thread row and embeddings no other agent holds. admin idempotent no yes
conversation.get Fetch one thread by id: thread metadata + optional messages. viewer read no
conversation.list Enumerate stored conversation threads for an agent / namespace. viewer read no
conversation.list_saved_messages Page through the messages a user saved, newest first, with no query: the first view of a "Saved" panel before anything is typed. viewer read no
conversation.save_message Save one chat message a user picked for search, whether or not the namespace records transcripts. writer idempotent no
conversation.saved_status Which of a conversation's messages a user has saved, in one call: a chat client draws every message's saved state when it opens the conversation. viewer read no
conversation.search Rank conversation messages by embedding similarity to query. viewer read no
conversation.search_saved_messages Hybrid search over only the messages one user saved with conversation.save_message, not the whole transcript. viewer read no
conversation.set_logging Toggle whether this namespace records conversation transcripts. admin idempotent no yes
conversation.threads Recent conversation threads of a namespace, newest first. viewer read yes
conversation.unsave_message Withdraw one message from a user's saved-message search. writer idempotent no
conversation.update Update one thread's title/metadata/run_id. writer idempotent no

cost

Fields for every cost op: operations/cost.md.

Operation Summary Role Kind Listed under all Audit
cost.agent_summary The coding agent's own spend (loom.agent_turn_usage) over a date window — the series cost.summary does not cover, which prices what LOOM spends upstream. viewer read yes
cost.budget_status This namespace's upstream spend in the last 24 h against its cap. viewer read yes
cost.record_turns The coding agent's own spend for one session, a batch of turns per call. writer idempotent no
cost.summary Cost rollup over a date window. viewer read no

decision

Fields for every decision op: operations/decision.md.

Operation Summary Role Kind Listed under all Audit
decision.chain Trace a decision's causal chain: upstream (what caused or influenced it) and/or downstream (what it went on to cause), up to 4 hops over the authored graph. viewer read no
decision.outcome Close the loop on a decision once reality has answered: record what actually happened and whether it worked (success). writer write no yes
decision.precedents BEFORE deciding, ask what was decided in similar situations: semantic search over past decisions (optionally within a category), each with its reasoning, rejected alternatives, and — when known… viewer read no
decision.record Record a DECISION as a first-class object — call it whenever you choose between options that matter later (a vendor, a design, a fix, a rollback). writer idempotent no yes

erasure

Fields for every erasure op: operations/erasure.md.

Operation Summary Role Kind Listed under all Audit
erasure.export Export the rows about a user or namespace, each section capped at section_limit. admin idempotent yes yes
erasure.list Audit-shaped roll-up of the org's erasures the caller may see: the org-wide view for an org admin, the namespace sagas of the caller's own namespaces otherwise. viewer read no
erasure.request Erase the rows about a user or namespace (the audit trail is kept). writer idempotent yes yes
erasure.status Check the status of an in-flight erasure request (queued, running, completed, failed). viewer read no

extraction_policy

Fields for every extraction_policy op: operations/extraction_policy.md.

Operation Summary Role Kind Listed under all Audit
extraction_policy.clear Remove the scope's policy. org_admin idempotent no yes
extraction_policy.get The scope's policy and the one its extractions run under. org_admin idempotent no
extraction_policy.set Set the scope's policy, replacing the one it held. org_admin idempotent no yes

facts

Fields for every facts op: operations/facts.md.

Operation Summary Role Kind Listed under all Audit
facts.expire_by_adapter Tombstone graph-level triples emitted by a specific extractor (e.g. a buggy adapter) without touching the parent memories. admin write no yes
facts.list Subject-relation-object triples from the entity graph, filtered by subject / object / relation / entity; optional source keys. viewer read yes
facts.path Find how two entities are connected: a bounded bidirectional breadth-first search over the same validity-filtered edge set facts.traverse walks, meeting in the middle. viewer read no
facts.related Return the entities that co-occur with input.entity via any relation, ranked by total co_occur (DESC). viewer read no
facts.traverse Walk the entity co-occurrence graph N hops out from a seed, one bounded query per hop. viewer read yes

grants

Fields for every grants op: operations/grants.md.

Operation Summary Role Kind Listed under all Audit
grants.approve Approve (or reject) a pending grant request. admin idempotent no yes
grants.create Grant another subject (user or service-account) viewer / writer / admin role on a namespace. admin idempotent yes yes
grants.list List active grants on a namespace — who has access, at which role. viewer read yes
grants.pending_for_me Every pending request in the namespaces the caller administers, in one statement. viewer read no
grants.revoke Remove a subject's grant on a namespace. admin idempotent no yes
grants.share_agent Let another agent of the caller's trust read, or write, the caller's own namespace. writer idempotent no yes
grants.unshare_agent Take back what the caller lent another agent of its trust. writer idempotent no yes

help

Fields for every help op: operations/help.md.

Operation Summary Role Kind Listed under all Audit
help.get Read one page of this build's documentation, or one section of it. viewer read no
help.search Search this build's documentation. viewer read no

inbox

Fields for every inbox op: operations/inbox.md.

Operation Summary Role Kind Listed under all Audit
inbox.list Inboxes the caller may see: those owned by namespace (the authorized namespace) plus, with mine_everywhere, every inbox in the org the caller may post to: one whose owner namespace the caller… viewer read no
inbox.policy_list List an inbox's trust policies. viewer read no
inbox.policy_set Set the trust mode an inbox owner chose for a poster and task kind (Loom stores it, never changes it). admin idempotent no yes
inbox.principals The identities loom already knows in the org — the poster picker's source. admin idempotent no
inbox.register namespace is the owner namespace (the caller must be its admin). admin idempotent no yes

insights

Fields for every insights op: operations/insights.md.

Operation Summary Role Kind Listed under all Audit
insights.catalog List the tables insights.query can read: each column with its type and meaning, how to read the table correctly (one live row per key, or one row per event), and the caps a statement runs under. viewer read no
insights.query Run one read-only SQL SELECT (or WITH) over the tables insights.catalog lists, for questions no other read answers: counts, rankings and trends over memories, conflicts, usage, documents and the… viewer read no

knowledge

Fields for every knowledge op: operations/knowledge.md.

Operation Summary Role Kind Listed under all Audit
knowledge.add WHAT: Ingest a document into the knowledge base for later retrieval via loom_search. writer idempotent yes
knowledge.bulk_add Batched ingestion: many documents in one CH round-trip. writer idempotent yes
knowledge.bulk_delete Soft-delete multiple documents by source_uri, in one commit. writer idempotent no yes
knowledge.dataset_approve Approve a dataset's schema, retyping the columns named: its rows are typed again from the stored extraction under a new snapshot. writer write no yes
knowledge.dataset_get The typed datasets an ingested file's tables became: their schemas, what needs a person's answer, the rows rejected and, on request, the first rows. viewer read no
knowledge.dedup_list List cross-URI doc duplicates and (optionally) chunk-overlap clusters. admin idempotent no
knowledge.dedup_resolve Resolve one document duplicate pair. admin idempotent no yes
knowledge.delete Soft-delete a document by source_uri: writes its tombstone. writer idempotent no yes
knowledge.formats The document formats this deployment reads, as knowledge.ingest sends them to its extractors, and the upload's limits. viewer read no
knowledge.get Fetch a single document by source_uri. viewer read yes
knowledge.ingest Extract an uploaded file (the extractor service parses it, the server checks what it returns) and publish it as a document revision, asynchronously: the answer names the job, and… writer write no
knowledge.ingest_cancel A pending job is cancelled at once; a running one stops before it publishes; a finished one stays as it ended. writer idempotent no
knowledge.ingest_status A knowledge.ingest job's state, stage, coverage, failure and published revision. viewer read no
knowledge.inspect Report a namespace's documents, read-only. viewer read no
knowledge.list Paginated listing of the documents of one namespace or several, for curation tools. viewer read yes
knowledge.outline A document's table of contents, as recorded on its chunks at ingest, and optionally one section's assembled text. viewer read no
knowledge.query Calculate over the live snapshots of ingested datasets with a typed plan: filters, inner joins, groups and aggregates, or the rows themselves. viewer read no
knowledge.reads How often agents opened each document over the last days (knowledge.get ledger rows; dashboard, assistant and bench traffic left out). viewer read no
knowledge.restore Undo a knowledge.delete or knowledge.bulk_delete of one document. writer idempotent no yes
knowledge.search Search the user's uploaded document library — bills, contracts, receipts, resumes, policies, manuals, technical docs. viewer read no
knowledge.source.add Register a document source on a namespace: a kind, the ids it reads and a read-only credential. admin write no yes
knowledge.source.check Probe a registered document source with its stored credential now (a check and a listing of each folder or project), nothing written. admin idempotent no
knowledge.source.inspect One registered document source: its config, its sync state and the documents it wrote (the 200 most recently ingested). viewer read no
knowledge.source.list The document sources registered on a namespace, with each one's sync state. viewer read no
knowledge.source.remove Retire a registered document source: its registry row goes inactive and its credential is cleared. admin write no yes
knowledge.source.rotate Replace a registered document source's credential. admin write no yes
knowledge.source.sync_now Record a request to sync one document source in its sync state: the sync worker starts its next pass with it. admin idempotent no yes
knowledge.synthesize Complete a task over WHOLE documents, not a search slice: every active chunk of the named documents is read in order, in windows that respect section boundaries, each window is noted once, and the… viewer idempotent no yes
knowledge.update_metadata Edit doc-level metadata (title, description, tags). writer idempotent no yes
knowledge.upsert Same fields as knowledge.add. writer idempotent no

learnings

Fields for every learnings op: operations/learnings.md.

Operation Summary Role Kind Listed under all Audit
learnings.list List learnings candidates by status (pending by default, promoted, rejected). viewer read no
learnings.quality Per-namespace approve-ratio rollup of the learnings queue. viewer read no
learnings.review Approve or reject a pending learning. admin idempotent no yes

memory

Fields for every memory op: operations/memory.md.

Operation Summary Role Kind Listed under all Audit
memory.agents_list Distinct agent names that have ever written into (org, namespace). agent + user_id are forced sentinels — we aggregate ACROSS them to discover which agents exist. viewer read yes
memory.aggregate Templated SQL aggregation over typed records in loom.memory. viewer read no
memory.apply One scope grammar for every write that can touch more than one row. writer write yes yes
memory.ask Ask a question and get a grounded answer synthesized from the caller's recalled memories (or, with allow_synthesis=False, just the memories). viewer read yes
memory.assign_category Link a memory to one of the namespace's registered categories. writer idempotent no yes
memory.auto_retirements The memories Loom retired on its own (the conflict resolver, newest_wins), newest record first, inside the request's read scope. viewer read no
memory.backlinks What points at one memory: its version chain, the digests whose lineage names it, the typed links in and out of it, how many evidence turns support it, and the memories that share its entities. viewer read no
memory.brief A task or question to orient on. viewer read yes
memory.bulk_get Fetch many memory entries by key in one CH round-trip. viewer read no
memory.bulk_set Insert many memory entries in one batched CH insert. writer idempotent no
memory.clear Bulk-tombstone memories in one scope. admin idempotent yes yes
memory.consolidate Periodic consolidation pass — merges fragmented memories about the same subject that slip past hash-dedup and extraction-time dedup. writer write yes yes
memory.copy_to Self-service copy of a memory into another namespace. writer write no yes
memory.cross_promote Cross-namespace promotion with provenance. viewer write no yes
memory.dedup_collapse Collapse every duplicate pair of a namespace onto its canonical — no LLM, every key kept, nothing tombstoned. writer idempotent no yes
memory.dedup_list List clusters of status='duplicate' rows in a namespace. admin idempotent no
memory.dedup_resolve Resolve one duplicate pair. admin idempotent no yes
memory.delete WHAT: Tombstone a memory by key (14-day recovery in the dashboard). writer idempotent yes yes
memory.delete_version Tombstone one version of a key under this exact identity, or nothing when the row under it has moved on. writer idempotent no yes
memory.demonstrate Test-time learning from memory: the nearest memories tagged as examples (default tag example, label carried as label:<value>), a similarity-weighted vote over their labels, the predicted label… viewer read no
memory.demote Revert a shared memory back to private. admin idempotent no yes
memory.digests List the session digests of a namespace. viewer read yes
memory.evidence List the source turns a memory was extracted from, with the supporting span and whether each link was cited by the extractor, matched lexically, or fell back to the whole window. viewer read yes
memory.export_evidence The raw chunks and session digests behind a namespace's memories, as portable rows (paged). viewer read yes
memory.exposure_summary Per-(actor, agent) distinct memory keys returned by reads of a namespace over a window — how many distinct records each token has extracted — computed for every token, from… admin idempotent no
memory.extraction_retry_mine Replay your failed deferred memory.set_from_messages batches once more, by queue_id. writer idempotent no
memory.extraction_status State of deferred set_from_messages batches. viewer read no
memory.extraction_status_mine Your deferred memory.set_from_messages batches, by the queue_id each call returned. viewer read no
memory.for_file What Loom knows about ONE file, shaped for the moment before an edit: memories whose files[] facet names the path (repo-relative or bare filename both match). viewer read yes
memory.get WHAT: Fetch one memory by exact memory_key. viewer read yes
memory.get_by_id Fetch a memory by its UUID (not memory_key). viewer read yes
memory.health Knowledge-base health for (org, namespace): how much of what is stored is ever recalled, what is silent, what earns its keep. agent + user_id are sentinels — the report aggregates across them. viewer read yes
memory.history Enumerate the version history of one memory_key. viewer read yes
memory.import Import items another memory system distilled, through every check a write makes. writer idempotent no
memory.import_curated Split a curated markdown doc into sections, write each via handle_memory_set, returning per-section verdicts. writer write no yes
memory.import_evidence Write exported evidence chunks and digests into a namespace, re-embedded here and linked to their memory keys. writer write yes yes
memory.inspect Inspect one user, agent or session of a namespace, read-only. viewer read no
memory.keys Every live row's identity and key in one read: a set an exporter can check its paged listing against, since a row that moves while pages are read can be skipped. viewer read no
memory.lineage Assemble the provenance chain for a SHARED memory. viewer read no
memory.link Author an explicit edge between two memories (or two entities). writer write yes yes
memory.list List memory keys under this identity, optionally filtered. viewer read yes
memory.lock Lock one row against a class of writes. writer write yes yes
memory.move Rename from_key to to_key, leaving the old key answering. writer write yes yes
memory.outcome External outcome signal for a memory row. writer write no yes
memory.outcome_run Apply one outcome to many recalled memories in a single call — the bulk form of memory.outcome, so callers skip a per-key loop. writer write yes yes
memory.outline A namespace's table of contents, read from structure alone: row counts by type, the dated sessions with their digest's first line, the hub entities by degree, the communities when a pass has computed… viewer read no
memory.owner_report The owner's view of their memory: what they own, who read it, how it was used. viewer read no
memory.pin WHAT: Save a standing fact and protect it. writer idempotent yes
memory.promote Promote a single source memory to the namespace's shared layer. admin write no yes
memory.proposal_decide Accept (→ active, served by default) or reject a list of proposals. writer idempotent no yes
memory.proposals List facts on trial (written with memory.set proposed=true) with the graded runs that relied on each — passes, fails — and what the namespace's proposal policy says (ready: accept / reject). viewer read no
memory.provenance Resolve a memory's origin for user-facing provenance. viewer read yes
memory.recall Search the raw conversation turns behind this namespace's memories — the messages memory.set_from_messages extracted from — by text and by time. viewer read yes
memory.record.conflicts Field-level disagreements recorded when a typed record superseded the active record for its logical key: which field, both values, both record ids and both citing memories. viewer read no
memory.record.history Every version of one typed record, newest first. viewer read yes
memory.record.query Typed records of one schema by field filters and predicates, as of a time. viewer read yes
memory.record.write Write one typed record (schema name + fields, optional validity window); a newer record for the same key supersedes the old. writer write yes yes
memory.redact Scrub the value of a historical memory row, preserving its audit entry. admin idempotent no yes
memory.reindex Re-embed a namespace's memories whose vectors were made by another embedding model (or all of them with force). admin idempotent no yes
memory.reject Mark a memory as explicitly rejected (extractor / user review decided the candidate fact is wrong), so it isn't re-extracted. writer idempotent no yes
memory.related Find memories sharing entities with the source memory. viewer read no
memory.resolve_orphan_duplicates Scan (org, namespace) for orphaned duplicate rows and re-activate them. writer idempotent yes yes
memory.restore Bring back a deleted memory (within 14 days) or one Loom retired on its own. writer idempotent yes yes
memory.search Semantic search over the agent's own memory. viewer read no
memory.search_trace Same shape as memory.search; returns the vector leg's per-candidate scoring breakdown (no fusion, assembly or reranker). viewer read no
memory.search_trace_log Read loom.search_trace_log for a namespace (requires the telemetry flag). viewer read yes
memory.set Save a fact to Loom — shared across every AI tool the user runs; native memory is the Claude-only scratchpad. writer idempotent yes
memory.set_from_messages Run LLM extraction on messages and write the extracted facts. writer write yes
memory.stack Compose a token-budgeted recall bundle for agent wake-up. viewer read no
memory.statuses The current status of some memories, by id: which automatic retirements still stand (the Review queue's Auto-resolved tab reads it). viewer read no
memory.sweep_expired Run one expiry-sweep pass now — the same pass the memory_expiry_sweep worker runs on its interval, scoped to one namespace. admin idempotent no yes
memory.timeline Return memories about an entity (or matching a tag filter) in strict temporal order — newest first, with optional since/until windows. viewer read no
memory.touch Change only a memory's expiry: set a new TTL (ttl_seconds) or clear it (clear_expiry), for one key or up to 1,000 (memory_keys), without rewriting its value, entities, conflict state or… writer write no
memory.unlock Lift a lock set by memory.lock (admin). admin idempotent no yes
memory.unpin Remove the write-time pin from one live memory. admin idempotent no yes
memory.update Key-addressed update: the fact changed or got more specific. writer write yes
memory.update_by_id Update a memory by UUID with an optimistic concurrency check. writer idempotent yes
memory.verify Attest to (or revoke the attestation on) one memory. writer idempotent yes yes

memory_schema

Fields for every memory_schema op: operations/memory_schema.md.

Operation Summary Role Kind Listed under all Audit
memory_schema.approve Approve (make active) or reject a proposed record schema. admin write no yes
memory_schema.list List a namespace's record schemas, active ones only unless include_proposed. viewer read no
memory_schema.propose Register a record schema as proposed, for an admin to approve or reject. writer write no yes
memory_schema.register Register a typed-record schema (named fields) for a namespace; typed records are then written against it. admin write yes yes

mentor

Fields for every mentor op: operations/mentor.md.

Operation Summary Role Kind Listed under all Audit
mentor.brief One agent's usage profile and the store's hints. viewer read yes
mentor.guide The agent guide this server ships; the same for every caller. viewer read no

namespace

Fields for every namespace op: operations/namespace.md.

Operation Summary Role Kind Listed under all Audit
namespace.audit Usage report for one namespace: is it being used as a memory, or as an object store? viewer read yes
namespace.browse Discover public namespaces in the org; anyone can join returned rows via namespace.join. viewer read yes
namespace.cancel_request Withdraw the caller's own pending elevation request. viewer idempotent no yes
namespace.delete Tombstone a namespace and stop accepting writes against it; the document sources it retires are named in sources_retired, also when deleted is false. admin idempotent no yes
namespace.get Fetch one namespace's metadata + settings (owner, visibility, feature flags, retention). viewer read yes
namespace.guide_get The namespace's guide: Markdown its writers keep on what it holds, its key layout and what its tags mean. viewer read no
namespace.guide_history The guide's revisions, newest first, with summary, note, writer and length. viewer read no
namespace.guide_set Save a new revision of the namespace's guide after you change one of its conventions: the whole text, a note, and expected_revision = the revision you read. writer idempotent no yes
namespace.inventory What one namespace holds and who appears in it, with what was not counted. viewer read no
namespace.join Self-add as a viewer on a public namespace. viewer idempotent no yes
namespace.leave Drop the caller's grant on a namespace. viewer idempotent no yes
namespace.list Enumerate every namespace the caller can see (own + granted + public). org_admin idempotent no
namespace.list_categories Enumerate registered categories with item counts. viewer read no
namespace.list_mine List namespaces the caller is a member of (own + granted). viewer read yes
namespace.list_ontology List the ontology terms (entity and relation kinds) registered for a namespace. viewer read no
namespace.mark_seen Acknowledge a new-invitation indicator on a namespace. viewer idempotent no
namespace.register Create a shared memory workspace within an org; caller becomes admin. viewer idempotent yes yes
namespace.register_category Register a category in a namespace. writer write no yes
namespace.register_ontology Register an entity type or relation verb for a namespace. admin idempotent yes yes
namespace.restore Restore a snapshot payload into a target namespace. viewer idempotent no yes
namespace.rollback Return every memory head in a namespace to the version it had at as_of. admin write no yes
namespace.search_categories Cosine-rank the category registry against a query. viewer read no
namespace.snapshot Freeze a namespace's curated state as a portable JSON payload. admin idempotent no yes
namespace.summary Aggregated read-only metadata for one namespace, for a single-shot dashboard tile (category/memory counts, top entities, recent activity). viewer read yes
namespace.taxonomy The de-facto taxonomy of a namespace — tags + entities across its memories. viewer read yes
namespace.tune Draft changes to a namespace's extraction rules, categories and guide from what its rows and the audit show, and to the chunking and extractor settings from what its documents show. viewer read no
namespace.validate Integrity report for one namespace, in one call, shaped for the agent that just wrote to it. viewer read yes

observe

Fields for every observe op: operations/observe.md.

Operation Summary Role Kind Listed under all Audit
observe.crystallize Mark a session's pending observations ready for extraction into memories (queues only). writer idempotent yes
observe.record Record one tool observation (input, output, files, error) into the episodic plane; no LLM call. writer idempotent yes

ops

Fields for every ops op: operations/ops.md.

Operation Summary Role Kind Listed under all Audit
ops.capabilities Identity is optional: a client discovers the surface with whatever token it holds (role check only; no namespace is addressed). viewer read yes
ops.health Run the deployment's self-checks (schema contracts, embedding stubs, ClickHouse parts, op mix, procedure plane, workers) and report each as ok, warn or fail. org_admin idempotent no
ops.projection_failures.list List recorded projection failures: derived rows (embeddings, graph edges, summaries) a write could not produce. org_admin idempotent no
ops.projection_failures.resolve Mark projection failures resolved by id without retrying them. org_admin idempotent no yes
ops.projection_failures.retry Retry open projection failures for a namespace, optionally one projection kind. org_admin idempotent no yes

org

Fields for every org op: operations/org.md.

Operation Summary Role Kind Listed under all Audit
org.model_calls The org's current setting; enabled and unlocked when it was never set. org_admin idempotent no
org.set_model_calls Switch the org's model calls off or on. org_admin idempotent no yes

policy

Fields for every policy op: operations/policy.md.

Operation Summary Role Kind Listed under all Audit
policy.check A hypothetical call: what would the rules decide right now? viewer read yes
policy.decisions List the recorded history-policy decisions for a namespace, optionally one verdict. viewer read no
policy.delete Remove a history-policy rule (tombstoned, so its past decisions stay explainable). admin idempotent no yes
policy.list The namespace's policy rules and the enforcement mode. viewer read yes
policy.set Create or replace a namespace history-policy rule (effect, actions, condition). admin idempotent no yes

procedure

Fields for every procedure op: operations/procedure.md.

Operation Summary Role Kind Listed under all Audit
procedure.add Register a procedural memory — a 'how to do X' recipe with structured (name, situation, steps) fields. writer write yes
procedure.evolve Consolidate a procedure's accumulated run traces into an improved graph: rank the proven path by SUCCESSFUL traversals, flag steps no run ever used as dead ends, flag steps and transitions that sit… writer write no
procedure.fork Copy a procedure from a namespace the caller can read into the request namespace, with its evidence reset. writer write no yes
procedure.list Enumerate registered procedures in the namespace (optionally filtered by memory_key prefix or tags). viewer read no
procedure.locate Where am I in this procedure, and what comes next? viewer read no
procedure.match Find procedures whose situation field is semantically closest to the caller's described situation. viewer read yes
procedure.record_run Report one execution of a procedure so loom can learn which path actually works. writer write no
procedure.revise Propose an edited topology for a procedure — you are the refiner. writer write no yes

profile

Fields for every profile op: operations/profile.md.

Operation Summary Role Kind Listed under all Audit
profile.activity Recent profile reads per agent — "which AI client read my profile, when?". viewer read yes
profile.append WHAT: Atomic append to an existing profile section. writer write no
profile.render Render every section in (org, namespace) into one prompt fragment. viewer read yes
profile.replace WHAT: Substring rewrite within a profile section. writer idempotent no
profile.set WHAT: Create or replace a profile section at label. writer idempotent no
profile.structured The user's structured profile and whether it is current. viewer read no

profile_schema

Fields for every profile_schema op: operations/profile_schema.md.

Operation Summary Role Kind Listed under all Audit
profile_schema.clear Clear the schema: no profile is built or rebuilt for the namespace, and reads answer no_schema. admin idempotent no yes
profile_schema.get The namespace's profile schema, its hash, and who set it when. viewer read no
profile_schema.set Set the namespace's profile schema. admin idempotent no yes

run

Fields for every run op: operations/run.md.

Operation Summary Role Kind Listed under all Audit
run.begin Open a RUN — one execution of a task — BEFORE you start working on it. writer idempotent yes yes
run.complete Close a run opened with run.begin — call EXACTLY ONCE when the task ends. writer write yes yes
run.get Replay one run: goal, status, final response, the memories it relied on, the memory_keys it wrote, how many memories it recalled and observed, and what its model turns cost. viewer read yes
run.grade A verdict on a CLOSED run, usually days after it — a maintainer confirmed the finding, CI passed, a reviewer rejected it. writer idempotent no yes
run.list A page of a namespace's agent runs and their match count (total), filtered and sorted. viewer read no

Fields for every search op: operations/search.md.

Operation Summary Role Kind Listed under all Audit
search.query Search every plane of the caller's Loom content in one call. viewer read yes

session

Fields for every session op: operations/session.md.

Operation Summary Role Kind Listed under all Audit
session.brief_delete Delete a session brief by brief_key when the user asks for it to be forgotten. writer idempotent no yes
session.brief_get Load a brief: by brief_key, else the newest brief a given session wrote (from_session), else the newest for project. viewer read no
session.brief_list List the session briefs in this namespace, newest first: key, revision, age, agent and goal, one line each. viewer read no
session.brief_save Revise (or start) one brief. writer idempotent no yes

task

Fields for every task op: operations/task.md.

Operation Summary Role Kind Listed under all Audit
task.accept Accept a triaged task into the inbox's backlog (owner side), optionally setting priority and constraints. writer write no
task.block Mark a task blocked, releasing its lease, with the reason and what it is blocked on. writer write no
task.cancel A transition anyone entitled may make, with a reason; fence is required only when the caller is the current owner of an in_progress task. writer write no
task.claim Claim a todo task under a lease; the returned fence guards every later progress, block or finish. writer write no
task.complete WHAT: Finish a task you claimed: pass the fence from task.pull and an outcome (links, ids, a short result). writer write no
task.counts Count tasks by status for one inbox or every inbox of a namespace. viewer read no
task.create namespace is the poster's own namespace; inbox the target. writer idempotent no
task.defer WHAT: Put a claimed task back with a resume_at; the sweeper returns it to the queue at that time. writer write no
task.fail WHAT: Mark a claimed task failed with a reason; the owner side may reopen it, and the inbox's max_attempts decides when it is blocked on a human instead. writer write no
task.get One task by task_id: its state, lease, poster, result and history. viewer read no
task.heartbeat WHAT: Renew the lease on a task you claimed (fence from task.pull) and optionally leave a progress note. writer idempotent no
task.history Return a task's event history (posted, accepted, claimed, progress, finished, ...). viewer read no
task.list Tasks in inbox (owner side) or, with posted_by_me, the tasks the caller posted anywhere in the org. viewer read no
task.progress Record a progress note on a claimed task and extend its lease. writer write no
task.pull namespace is the inbox's owner namespace; the caller must be a writer there. writer write no
task.reassign Owner side: cancel here, re-post into another inbox as a child task (the destination's trust policy applies to the original poster). writer write no
task.reopen A transition anyone entitled may make, with a reason; fence is required only when the caller is the current owner of an in_progress task. writer write no
task.resume A deferred task back to todo now, ahead of its resume_at. writer write no
task.unblock Owner side, or the poster when the task is blocked on the sender. writer write no
task.update Edit the brief. writer write no
task.updates The sender's cursor: events on tasks this caller posted (or, with inbox, every event in an inbox the caller owns) after since_seq. viewer read no
task.wont_do A transition anyone entitled may make, with a reason; fence is required only when the caller is the current owner of an in_progress task. writer write no

tracker

Fields for every tracker op: operations/tracker.md.

Operation Summary Role Kind Listed under all Audit
tracker.answer Answer a tracker question in prose — or from an artefact's anchors — by running the catalogue's templates: escalation / incident context, a customer across channels, incidents / escalations… viewer read no
tracker.binding What this namespace may ask the tracker plane: a QA namespace answers itself; a code namespace answers the tracker namespace bound to it (LOOM_TRACKER_CODE_NAMESPACE_BINDINGS_JSON), passed through… viewer read no
tracker.component One component's risk snapshot and its open issues, most severe first. viewer read no
tracker.contract The record contract as the register page shows it before anyone connects: every table loom reads, required or optional, each column's family, the type a view writes, whether a default is safe, what… viewer read no
tracker.duplicate_check Does this draft already exist? viewer read no
tracker.flaky Is this test a known flaky? viewer read no
tracker.item The tracker record of up to ten issue / PR numbers: component, severity, bisect verdict and branches still affected, test presence, CI result, reviewers, backport lineage, and the fixes / backports… viewer read no
tracker.links Which PR probably fixed this issue — or which issue this PR probably fixed — when nobody wrote the link down. viewer read no
tracker.release Release readiness for one version (26.3): the blocker rows with their status and the latest health snapshot. viewer read no
tracker.similar The reports that already say it: duplicate and related issues / PRs for a pasted report (text), an existing item (issue_number — its own title, body, component, versions and error code become the… viewer read no
tracker.source.add Register a tracker source: a ClickHouse endpoint and database holding the record contract (docs/features/tracker/record-contract.md), a read-only credential, and the tracker namespaces that read it. viewer write no yes
tracker.source.check Run the record-contract check on a configured tracker source now: the same read the boot gate runs, its verdict cached. viewer read no
tracker.source.inspect Connect with a read-only credential and say what the database holds — every table the user can read, its columns and types — plus a first mapping of it onto loom's logical model. viewer read no
tracker.source.list The tracker sources of an org: every configured source with its contract verdict, breaker and freshness, and the tracker namespaces reading it — each with the directory row's effective join rule and… viewer read no
tracker.source.remove Retire a registered tracker source and its namespaces. viewer idempotent no yes
tracker.source.rotate Replace a registered source's credential. viewer write no yes
tracker.source.set_mapping Change a registered tracker's mapping, with the same checks as add; mapping: null returns it to the views case. viewer idempotent no yes
tracker.test_signal Flaky, regression or infrastructure? viewer read no

ui

Fields for every ui op: operations/ui.md.

Operation Summary Role Kind Listed under all Audit
ui.vitals Record one dashboard page's web vitals; the per-op ledger row the transport writes carries the fields. viewer idempotent no

webhook

Fields for every webhook op: operations/webhook.md.

Operation Summary Role Kind Listed under all Audit
webhook.deliveries The namespace's webhook events of the last 3 days and their delivery state. admin idempotent no
webhook.list The namespace's memory webhooks. admin idempotent no
webhook.register Register a URL that is told when memory in the namespace changes. admin idempotent no yes
webhook.remove Remove one memory webhook; none of its events is sent after the call, save a POST already in flight. admin idempotent no yes

working_memory

Fields for every working_memory op: operations/working_memory.md.

Operation Summary Role Kind Listed under all Audit
working_memory.append Append text to a working-memory block, creating it when missing. writer write yes
working_memory.delete Delete one working-memory block. writer idempotent no
working_memory.get Fetch one working-memory block by key. viewer read no
working_memory.render Render working-memory blocks as XML or markdown. context.pack already includes this section; direct render is mainly for SDK or custom orchestration code. viewer read yes
working_memory.replace Replace exact text inside a working-memory block. writer idempotent no
working_memory.set Overwrite one working-memory block. writer idempotent yes