---
title: session operations
---

The exact fields each `session.*` operation takes and returns.

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

Every op is `POST /v1/<op>` over HTTP and the MCP tool `loom_<op>`. The identity fields (`org`, `namespace`, `agent`, `user_id`, `session_id`) are filled from the token and the MCP session when a transport can; for an HTTP call with no token on a single-user server, the install's org on every op but `code.*` and `tracker.*` (which keep their plane's), and on [some ops](/docs/reference/http-api#request) its namespace and agent; see [identities and namespaces](/docs/concepts/identities-and-namespaces). The [operations index](/docs/reference/operations) explains role, kind and the MCP `all` listing. Unknown input fields are served and named in `ignored_args`.

<!-- prettier-ignore-start -->

## `session.brief_delete`

Delete a session brief by brief_key when the user asks for it to be forgotten.

`POST /v1/session.brief_delete` · MCP `loom_session_brief_delete` · role `writer` · idempotent · audited · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | required | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `session_id` | `str` | `'-'` | The session or conversation the row belongs to; `'-'` for none. |
| `run_id` | `str` | `'-'` | The agent run (task scope) the call belongs to; `'-'` for none. |
| `brief_key` | `str` | required | The brief to delete, as session.brief_list shows it. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `deleted` | `bool` | False when no live brief has this key (unknown or already deleted). |
| `brief_key` | `str` | Echo of the input `brief_key`. |
| `revision` | `int` | The revision the brief was at when deleted; 0 when nothing was deleted. |

## `session.brief_get`

Load a brief: by `brief_key`, else the newest brief a given session wrote (`from_session`), else the newest for `project`.

`POST /v1/session.brief_get` · MCP `loom_session_brief_get` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | required | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `session_id` | `str` | `'-'` | The session or conversation the row belongs to; `'-'` for none. |
| `run_id` | `str` | `'-'` | The agent run (task scope) the call belongs to; `'-'` for none. |
| `brief_key` | `str` | `''` | The brief to load; takes precedence over `from_session` and `project`. |
| `from_session` | `str` | `''` | Load the newest brief this session id contributed to. |
| `project` | `str` | `''` | Load the newest brief of this project (used when `brief_key` and `from_session` are empty). |
| `revision` | `int` | `0` | 0 = the current revision; N = that revision from the history. |
| `include_sections` | `bool` | `False` | Also return the structured `sections`; False returns only `rendered`. |
| `full` | `bool` | `False` | Append the client's own summary from its last compaction, verbatim, below the brief (up to ~15k chars more). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `found` | `bool` | False when no brief matched, the brief is deleted, or the revision is not in its history. |
| `brief_key` | `str` | Key of the brief that matched. |
| `revision` | `int` | The revision returned (the current one unless `revision` was asked for). |
| `rendered` | `str` | The brief as text, with the client's compaction summary appended when `full`. |
| `sections` | `BriefSections \| None` | The structured brief; None unless `include_sections` was set. |
| `project` | `str` | Project stored on the brief. |
| `branch` | `str` | Branch stored on the brief. |
| `head_sha` | `str` | Commit the checkout was at when this revision was saved. |
| `author` | `str` | Who wrote the revision: `llm`, `deterministic` or `model` (the calling agent). |
| `trigger` | `str` | What prompted the revision's save (`precompact`, `session_end`, `stop`, `manual` or `model`). |
| `actor` | `str` | The principal that saved the revision (`human:<subject>` / `process:<subject>`): a namespace-wide writer may save to a user's own `~<user>~` brief. |
| `source_sessions` | `list[str]` | Session ids that contributed to the brief, oldest first (the last 20). |
| `updated_at` | `datetime \| None` | When the returned revision was saved. |
| `age_seconds` | `int` | Seconds since `updated_at`. |
| `revisions` | `int` | How many revisions the brief's history holds. |
| `events_total` | `int` | Events condensed into the brief over its whole life. |
| `source_chars` | `int` | Characters of event text condensed into the brief over its whole life. |
| `brief_chars` | `int` | Length of `rendered` as stored, in characters. |
| `deleted` | `bool` | True when the brief was deleted by its writer; nothing else is served then. |

## `session.brief_list`

List the session briefs in this namespace, newest first: key, revision, age, agent and goal, one line each.

`POST /v1/session.brief_list` · MCP `loom_session_brief_list` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | required | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `session_id` | `str` | `'-'` | The session or conversation the row belongs to; `'-'` for none. |
| `run_id` | `str` | `'-'` | The agent run (task scope) the call belongs to; `'-'` for none. |
| `project` | `str` | `''` | Only briefs of this project; empty = every project. |
| `mine_only` | `bool` | `False` | True = only the calling agent's briefs; default every agent's. |
| `from_session` | `str` | `''` | Only briefs this session id contributed to; empty = no session filter. |
| `limit` | `int` | `10` | At most this many briefs (1-50). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `briefs` | `list[SessionBriefSummary]` | Live briefs, most recently saved first; empty when the namespace holds none. |
| `rendered` | `str` | One line per brief, ready to show. |

## `session.brief_save`

Revise (or start) one brief.

`POST /v1/session.brief_save` · MCP `loom_session_brief_save` · role `writer` · idempotent · audited · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | required | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `session_id` | `str` | `'-'` | The session or conversation the row belongs to; `'-'` for none. |
| `run_id` | `str` | `'-'` | The agent run (task scope) the call belongs to; `'-'` for none. |
| `brief_key` | `str` | `''` | The brief's address in the namespace. |
| `project` | `str` | `''` | Project the work belongs to; with `branch` it forms the automatic key. |
| `repo` | `str` | `''` | Repository the work is in, stored on the brief; empty keeps the stored value. |
| `branch` | `str` | `''` | Branch the work is on; with `project` it forms the automatic key. |
| `head_sha` | `str` | `''` | Commit the checkout was at when saving; empty keeps the stored value. |
| `trigger` | `Literal['precompact', 'session_end', 'stop', 'manual', 'model']` | `'manual'` | What prompted the save: `manual` and `model` always save; the automatic `precompact`, `session_end` and `stop` store nothing while the namespace's recording is off. |
| `events` | `list[BriefEvent]` | *(computed)* | What happened since the last save (at most 4000 events), condensed into the revision. |
| `sections` | `BriefSections \| None` | `None` | A brief the calling agent wrote from its own context: the filled sections replace the stored ones (decisions / dead ends append). |
| `event_cursor` | `str` | `''` | Opaque client position the events end at (a transcript line index). |
| `if_revision` | `int \| None` | `None` | Compare-and-set: refuse (409) unless the stored revision is this one. |
| `use_llm` | `bool \| None` | `None` | Force the deterministic builder (False) or the model (True); None = the deployment setting. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `brief_key` | `str` | The key the brief was saved under (the resolved automatic key when none was given). |
| `revision` | `int` | The brief's revision after this call (the stored one when unchanged; 0 when none is live). |
| `changed` | `bool` | True when a new revision was written; False when `reason` says why not. |
| `author` | `str` | "llm" (revised by the model), "deterministic" (no model configured, or it failed; never under an operator's extraction policy), "model" (the calling agent wrote the sections). |
| `reason` | `str` | Why nothing was written: `nothing-to-save`, `recording_off`, `already-saved` or `not-revised` (an operator's extraction policy is in force and there is no model to revise the brief); empty when `changed`. |
| `rendered` | `str` | The brief as text, ready to show; the stored one when nothing changed. |
| `stats` | `SessionBriefStats` | Counts for this save: events, windows, sizes, tokens and the model used. |

<!-- prettier-ignore-end -->
