session operations

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

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 its namespace and agent; see identities and namespaces. The operations index explains role, kind and the MCP all listing. Unknown input fields are served and named in ignored_args.

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.