An AI coding session is a record, not a chat. It resumes where the same project, computer, branch and actor left off, asks which rules apply before it touches a file, logs what it decided, files what it deferred, ends with a history entry and reports what it consumed — over one MCP server, a REST API and a dashboard.
build session
start_build_session → 200 resumedcurrent state · lead
Lease sweep loses to a live lease; ack refuses a re-pended row. Next: the concurrent crossing-boundary case, then the guard test.
usage · 84.2k tokens · token counts, not dollars · illustrative
Nine tool calls, in the order an agent makes them. This is the protocol this repository runs on itself, every session.
The same project, computer, branch and actor gets its active session back (200); otherwise a fresh one starts (201). A unique index makes that true, so a reconnect never mints a duplicate.
start_build_session Pass the file paths, operations, languages, code patterns and project attributes of the change; only the rules whose every populated trigger dimension matches come back, ranked by how often they have been retrieved.
query_applicable_rules The session carries a rolling current-state lead — the paragraph the next session reads first. A cross-machine resume the tuple cannot catch is linked explicitly as a continuation.
prepend_build_session_lead One entry per decision, auto-linked to the open session. The log is append-only by a database trigger; a correction is a new entry that points at the one it supersedes.
append_decision_log Anything not done becomes an open item with a priority and a category. It is later triaged, assigned or reprioritised; resolving needs a closing PR, commit or notes, dismissing needs a reason, and both are final.
file_backlog_item Sets the end instant and persists the closing history entry, plus the pull requests and commits the session produced. Re-ending a closed session returns it unchanged.
end_build_session Five token classes and turns per transcript, keyed on the transcript id so a re-report overwrites and never double-counts. A Claude Code SessionEnd hook does this for you.
record_build_session_usage A review, a test run — anything another agent must do leaves as a typed message and waits in that agent’s inbox until its next get_pending. Recipients are AI accounts in the same workspace.
send Recurring pain is filed as a lesson and moves forward only — observed, documented, enforced. A rule is derived only from an enforced lesson, and step 2 returns it next time.
derive_rule
A build session opens with start_build_session — resumed if this project, computer, branch and
actor already have one, enforced by a unique index. Before touching a file the agent calls
query_applicable_rules with the files, operations and languages it is about to change and gets
back only the rules that match. It works. It writes append_decision_log for each material
decision and file_backlog_item for each deferral. It closes with end_build_session
and reports record_build_session_usage. Anything that needs another agent — a review, a test
run — leaves as a send
and waits in that agent's inbox until its next get_pending. Each tool links to its row in
the catalogue; the three-step setup is on
the docs page, and the skills and hooks we run it with are on
the Claude Code page. Why a session needs a
state layer at all — what context loss is, and where a state file, a summary or a re-injecting hook
breaks — is the context-loss guide; how
we run the two skills ourselves, step by step, is
the start-session and end-session guide.
None of this displaces the memory your coding client keeps for itself; the two hold different things,
and which is which is set out row by row, cited on both sides, on
PostMQ and Claude Code auto memory.
Every ledger — sessions, decisions, backlog, lessons, rules, usage — is scoped to a project inside your workspace, and each card names the object it is made of.
The same project, computer, branch and actor gets the same active session back — 200 on resume, 201 on create — enforced by a unique index rather than a client-side check, so two concurrent starts cannot mint two active sessions.
A rolling current-state lead the next session reads first; the prior lead is demoted, not lost. A session can be linked as the continuation of one on another machine or branch, and it ends with a history entry.
Decisions cannot be edited or deleted — a database trigger rejects deletes and every update except source links. Corrections are new entries that point at the entry they supersede; the original is never edited.
File, triage, prioritise, assign, reprioritise; staleness is a persisted instant, acknowledged explicitly. Resolve requires a closing PR, commit or closing notes; dismiss requires a reason; resolved stays resolved.
Describe the change — file globs, operations, code patterns, languages, project attributes — and get back only the rules whose every populated trigger dimension matches. Each rule shows how often it has been retrieved, and the dashboard replays the exact retrieval an agent runs.
Rules can only be derived from lessons in the enforced state, and a lesson cannot be enforced without a documented prevention mechanism (checked by a database constraint). Status moves forward only; mis-filed records can be hard-deleted by an authorised credential.
Five token classes and turns per build session, rolled up per project, day, week or month. Token counts, not dollars. Idempotent per transcript. One Claude Code SessionEnd hook, or any client calling the tool.
Cumulative flow, throughput, aging work in progress and cycle time — dashboard only, read straight from the backlog, and honest about having no transition history.
Import existing markdown ledgers: preview first, then commit; entries already imported are skipped by a fingerprint of their source block, so re-running is safe.
Lesson candidates are proposed by an optional LLM detection pass over your resolved backlog (bring your own Anthropic key, off by default); they cannot be typed in by hand, and each candidate is promoted, rejected or superseded once — terminal states are absorbing. Every session-state lifecycle event — sessions started and ended, decisions appended and corrected, backlog filed, triaged, assigned and reprioritised, lessons and rules created and changed — is written into the same tamper-evident SHA-256 audit chain as messaging: 38 of 123 event types. High-frequency touches such as pings and usage reports are deliberately not audited. A workspace can browse its own chain in the dashboard and read it over REST and MCP, with the operator-significant families withheld; the mechanism is on the security page.
The MCP tool, the versioned REST route under /v1 and the dashboard page — all three run the same service layer, and for every session-state aggregate REST and MCP serialize through one shared serializer and are tested byte-identical.
{
"method": "tools/call",
"params": {
"name": "start_build_session",
"arguments": {
"project_id": "01K…",
"computer": "my-laptop",
"branch": "feat/lease-sweep",
"intent": "make the expiry sweep lose to a live lease"
}
}
} POST /v1/build-sessions Authorization: Bearer pmq_…redacted… Content-Type: application/json { "project_id": "01K…", "computer": "my-laptop", "branch": "feat/lease-sweep", "intent": "make the expiry sweep lose to a live lease" }
app.postmq.com/build-sessions active sessions first, then closed
app.postmq.com/build-sessions/{id} current state, lead, history entry, usage {
"method": "tools/call",
"params": {
"name": "query_applicable_rules",
"arguments": {
"project_id": "01K…",
"file_paths": ["src/PostMQ.Infrastructure/Accounts/CredentialIssueService.cs"],
"operations": ["modify"],
"languages": ["csharp"],
"project_attributes": ["sql-locking"],
"task_context": "take the account row lock before inserting a credential"
}
}
} POST /v1/rules/applicable Authorization: Bearer pmq_…redacted… Content-Type: application/json { "project_id": "01K…", "file_paths": ["src/PostMQ.Infrastructure/Accounts/CredentialIssueService.cs"], "operations": ["modify"], "languages": ["csharp"], "project_attributes": ["sql-locking"], "task_context": "take the account row lock before inserting a credential" }
app.postmq.com/applicable-rules the same retrieval, replayed by a person
app.postmq.com/rules/{id} one rule: triggers, retrieval_count, last_retrieved_at {
"method": "tools/call",
"params": {
"name": "append_decision_log",
"arguments": {
"title": "Ack and sweep predicates live in one UPDATE",
"body_markdown": "Both predicates in the same statement; the loser matches zero rows.",
"entry_date": "2026-08-18",
"has_public_contract_impact": false
}
}
} POST /v1/decision-log Authorization: Bearer pmq_…redacted… Content-Type: application/json { "title": "Ack and sweep predicates live in one UPDATE", "body_markdown": "Both predicates in the same statement; the loser matches zero rows.", "entry_date": "2026-08-18", "has_public_contract_impact": false }
app.postmq.com/decision-log newest first; filter by project; search title and rationale
app.postmq.com/decision-log/{id} one entry, its rationale, what it corrects, its session {
"method": "tools/call",
"params": {
"name": "record_build_session_usage",
"arguments": {
"build_session_id": "01K…",
"client_session_id": "8f3c…",
"input_tokens": 41200,
"cache_write_5m_tokens": 12800,
"cache_write_1h_tokens": 0,
"cache_read_tokens": 1810400,
"output_tokens": 22600,
"turns": 118,
"sidechain_turns": 9,
"agent": "claude-code"
}
}
} POST /v1/usage Authorization: Bearer pmq_…redacted… Content-Type: application/json { "build_session_id": "01K…", "client_session_id": "8f3c…", "input_tokens": 41200, "cache_write_5m_tokens": 12800, "cache_write_1h_tokens": 0, "cache_read_tokens": 1810400, "output_tokens": 22600, "turns": 118, "sidechain_turns": 9, "agent": "claude-code" }
app.postmq.com/usage tokens and turns per project, day, week or month app.postmq.com/flow cumulative flow, throughput, aging WIP, cycle time
A mechanism per row; the badge says whether it ships on, ships off, or is roadmap.
| what holds | how | scope |
|---|---|---|
| Session start is idempotentC06 | UQ_build_sessions_active — a filtered unique index on (project, computer, branch, actor); 201 on create, 200 on resume; concurrent starts cannot mint two active sessions | shipped |
| Decisions cannot be edited or deletedC07 | tg_decision_log_entries_append_only rejects DELETE and every UPDATE except the two source links; a correction is a new entry with corrects_entry_id | shipped |
| Backlog terminal states are absorbingC14 | tg_backlog_items_terminal_absorbing; resolve requires a closing PR, commit or closing notes; dismiss requires a reason | shipped |
| A rule matches on every populated dimensionC09 | file globs · operations · code patterns · languages · project attributes, AND across the populated ones; retrieval_count and last_retrieved_at bumped on each hit | shipped |
| Rules derive only from enforced lessonsC12rules are advisory to the agent — enforcement stays in your CI | derive_rule refuses a lesson that is not enforced; CK_build_lessons_enforced_requires_prevention refuses enforced without a prevention mechanism; status triggers move forward only | shipped |
| Every lifecycle event is on the audit chainC19pings, usage reports and retrieval-count bumps are deliberately not audited | 38 of 123 event types, written into the workspace’s SHA-256 chain in the same transaction as the row they record | shipped |
| Usage is idempotent per transcript, in tokensC17 | UQ_build_session_usages_report on (build session, transcript); five token classes + turns; token counts, not dollars; self-reported by the agent or the hook | shipped |
| REST and MCP return the same bytesC05 | one serializer per session-state aggregate, pinned by nine byte-parity test classes | shipped |
| Search is a LIKE matchC62 | query_decisions, query_backlog and search_build_sessions match an escaped substring with SQL LIKE, newest first, capped at 50; query_lessons matches the same way but comes back in lifecycle order, least-advanced first — not full-text search | shipped |
| Paging style differs by surfaceC100 | list_decision_log and list_build_sessions are keyset-paged over an opaque signed cursor; list_backlog_items and query_lessons are offset-paged with a total; query_decisions, query_backlog and search_build_sessions take neither cursor nor offset — they return a capped top-N | shipped |
| Flow metrics are dashboard-onlyC18 | /flow reads the backlog as it stands: no transition history, so aging is since creation, dismissed items are excluded, and there is no REST or MCP surface | shipped |
| LLM assist is optional and off by defaultC13 | lesson-candidate detection and rule enrichment run only when your own Anthropic key is configured; they propose, and a person promotes | default-off |
| Import dedups by fingerprint over the raw blockC20 | SHA-256 of each entry’s source block; preview first (dry run), commit once; an edited entry re-imports as new | shipped |
A decision log, a backlog, build-session history — import_session_state_from_markdown parses
the corpus (up to 1 MiB per call; the REST multipart upload takes larger files), previews it as a dry run,
and commits it on the second call. Entries already imported are skipped by a fingerprint of their raw
source block, so re-running is safe, and every run is an append-only record with parsed, committed,
skipped and errored tallies.
Three honest lines. The fingerprint is over the raw block, so an edited entry re-imports as new rather than
updating the old one. The parser is the SpecStep markdown convention (SpecStepConvention.v1);
another shape needs a parser first. Dry runs are not audited — only a commit lands on the audit chain.
Setup is on the docs page; the import tools are in
the catalogue.
As of 2026-09-02 — the project's own ledger and git history, read at build.
We run PostMQ on PostMQ; every number here is generated from the project's own ledger at build — never typed — and the dogfood check fails the build when the file goes stale. The commit trailer is what ties a commit to the session that produced it.
SpecStep, Valuly and MeetCrew were built with the same session-state system PostMQ hosts.
Create a workspace, connect your agent, call start_build_session.