Briefs

A brief is a piece of fresh context you drop into the system between triage runs. Slack you got at 7 a.m., a meeting note from yesterday, an email from a carrier, a news headline that changes priorities — anything that should influence how the next rerank scores tasks.

Briefs are persisted in the briefs SQLite table and pulled into the prompt of the next triage run. Once consumed by a successful run, a brief's consumed_in_run_id is set so it won't be re-included.

Sources

The source field is one of:

• slack
• meeting
• email
• news
• personal
• other

Defined at optimalOS/src/routes/briefs.ts:9-20. The source is included in the prompt to give the model a hint about credibility and freshness.

API

Create a brief

POST /api/briefs
Content-Type: application/json

{
  "source": "slack",
  "body": "Carrier says March returns truck is delayed two days.",
  "tags": ["returnpro", "logistics"]
}

Response: { "id": 17, "created_at": "2026-04-27T14:02:11Z" }

Validation: source and body are required and must be non-empty. tags is optional.

Code: optimalOS/src/routes/briefs.ts:9-20.

List briefs

GET /api/briefs?consumed=false

consumed defaults to false (returns only unconsumed briefs). Pass consumed=true to see consumed ones.

Code: optimalOS/src/routes/briefs.ts:22-29.

Delete a brief

DELETE /api/briefs/:id

Code: optimalOS/src/routes/briefs.ts:31-36.

Data model

The briefs table (created in migration v5, optimalOS/src/db/migrations.ts:172-183):

Column	Type	Notes
id	INTEGER PK AUTOINCREMENT
source	TEXT NOT NULL	One of the source values above.
body	TEXT NOT NULL	The brief content.
tags	TEXT	JSON array, optional.
created_at	TEXT	Defaults to now.
consumed_in_run_id	INTEGER FK→triage_runs(id)	Null until consumed.

Indexes: idx_briefs_unconsumed on the partial condition consumed_in_run_id IS NULL, and idx_briefs_created on created_at DESC.

How a brief gets consumed

1. You POST /api/briefs with new context.
2. Next triage run snapshots all briefs where consumed_in_run_id IS NULL and includes them in the prompt.
3. On success, the workflow runs markBriefsConsumed(db, briefIds, runId) (optimalOS/src/triage/db.ts:55-62) which updates consumed_in_run_id.
4. The widget header decrements its unconsumed-brief count on the next refresh.

If the run fails, briefs stay unconsumed and will be picked up by the next attempt.