HTTP API and authentication
The HTTP API gives local clients and external integrations one way to create, process, search, and remove memory data. Versioned /v1 routes are the current server contract. Local /api routes support the desktop worker, viewer, hooks, imports, corpus work, duplicate review, work review, logs, backups, and media. Authentication adds team and optional project boundaries before a versioned route can read or change data. Local worker protection uses host, origin, and optional local-token rules instead of the server API-key flow. Older session routes and remote hook-spool routes remain as compatibility links for clients that have not moved to the newer contracts. The API connects the local runtime API with server jobs and provider work described in server jobs and process supervision.
Route surface
Route families
The server exposes route families with different roles. The local runtime uses SQLite-backed routes, while the deployable server runtime uses Postgres-backed routes. Both present the same main /v1 resource model where their runtime supports it. The local worker also serves data feeds, session capture, search and context, cloud-sync status and recovery, team knowledge, work state, work review, setup, logs, backups, media, and local controls. Compatibility paths sit beside the canonical paths so older clients can continue to work during migration.
| Family | Purpose | Main paths |
|---|---|---|
| Versioned API | Current client and integration contract | /v1/info, /v1/projects, /v1/sessions, /v1/events, /v1/memories, /v1/search, /v1/context |
| Server-beta operations | Team jobs, API key links, usage, deletion, and remote recall | /v1/jobs, /v1/teams/:teamId/jobs, /v1/projects/:projectId/jobs, /v1/keys, /v1/connect, /v1/usage, /v1/mcp |
| Local worker data | Viewer feeds, session data, tool-use detail, imports, deletion, and processing state | /api/observations, /api/summaries, /api/prompts, /api/import, /api/processing-status |
| Local worker capture | Hook session intake, advisor records, manual memory writes, and memory-file ingest | /api/sessions/*, /api/advisor-calls, /api/memory/save, /api/memory/ingest |
| Local worker knowledge | Saved corpora, long-running corpus queries, and near-duplicate review | /api/corpus, /api/dedup/* |
| Local worker experience | Work state, work review, setup, live events, deliverables, and recorded files | /api/work-state, /api/work-view/*, /api/setup/*, /api/deliverables/:id/:filename |
| Local worker search and context | Memory search, timelines, context previews, and context injection | /api/search*, /api/timeline*, /api/context/* |
| Local worker support | Settings, dependency health, logs, backups, media, local MCP state, runtime health, and cloud-sync controls | /api/settings, /api/settings/dependency-health, /api/logs, /api/backup/*, /api/media/:id/*, /api/mcp/*, /api/health, /api/sync/* |
| Remote hook intake | Authenticated delivery from a remote hook spool | /api/spool/ingest |
| Team knowledge proxy | Team status, shared board, project brief, and read-only team search | /api/teambrain/status, /api/teambrain/board, /api/teambrain/brief, /api/teambrain/search |
| Legacy compatibility | Accept older worker-shaped session calls | /api/sessions/observations, /api/sessions/summarize |
New integrations should use /v1 directly. Remote hook clients use /api/spool/ingest only when remote capture is configured. The local runtime starts and serves these routes as described in Local runtime API. Local client behavior is described further in Interactive viewer client, while the worker side of generation jobs is described in Server jobs and process supervision.
References: src/…/ServerService.ts• L178-210 src/…/Server.ts• L216-326 src/…/ServerV1Routes.ts• L61-75 src/…/ServerV1PostgresRoutes.ts• L162-246 src/…/DataRoutes.ts• L231-257 src/…/WorkViewRoutes.ts• L775-973
Resource contract
The versioned API models memory work as projects, sessions, agent events, observations, and generation jobs. Clients can send raw events for later generation or write a memory directly for manual use. Read routes return scoped records, while write routes return the created or changed record and a job descriptor when generation is involved. Job routes also let an authorized operator inspect and control background work without changing the event or memory contract.
The local worker API serves a separate desktop contract. It lets the viewer page through stored content, search and render context, inspect tool-use bodies by explicit ID, import or remove local records, read logs, create and list database snapshots, review work state, and fetch private media. It also accepts advisor-call records, builds and queries saved knowledge corpora, records near-duplicate review, exposes setup and work-review state, reports cloud-sync health and recovery, and proxies team knowledge for approved local clients. These routes use the worker's host, origin, local-page, and optional local-token boundaries rather than the server's team API-key boundary.
The data routes keep disclosure progressive. Lists return cheap indexes and size hints. Full observations or raw tool bodies require explicit IDs, and both batch forms are bounded. Import accepts partial batches and reports each rejected row instead of hiding a partial result. Memory-file ingest stores native memory files as direct observations and reports stored, duplicate, skipped, and failed items. Deletes protect cloud replicas, remove local session side data, invalidate context, and notify open viewers after the change commits.
| Resource or capability | Contract |
|---|---|
| Projects | List or read projects. Create projects with a team-scoped write key. A project-scoped key cannot create another project. |
| Sessions | Start or find sessions. An external session identity can make start idempotent within its platform and project. End sessions to create a summary job. Local deletion identifies a session by platform and content-session ID. |
| Events | Write one event or a batch of up to 500 events. Read an event and its linked observations. generate=false stores the event without a generation job. |
| Memories | Write or read an observation, search observations, build a context string, and delete one observation or all memory for a project. Local SQLite writes require at least one searchable field. Postgres manual writes can use generationKey so repeated writes return the existing observation instead of creating a duplicate. |
| Jobs | Read one job or filtered team/project lists. Read keys can inspect status. Write keys can retry failed work or cancel work. Job payloads need explicit admin access. |
| Recall | Use /v1/mcp for authenticated, read-only search, context, and recent-memory tools. |
| Usage and audit | Read month-to-date usage for a team and inspect project audit records where the route set supports them. |
| Local worker data | Read observations, summaries, prompts, sessions, advisor calls, tool-use indexes, and selected tool-use bodies. Deletes preserve cloud-sync rules and update live viewers. |
| Local knowledge | Build, list, refresh, prime, query, and remove saved corpora. Long operations can use JSON or server-sent events. List duplicate candidates, record a review verdict, and run an opt-in scan. |
| Local worker operations | Hook clients can initialize sessions, add observations, request summaries, and mark session end. Local clients can save memory, ingest memory files, inspect or change approved worker settings, manage work state, manage work review, focus sharing, setup state, and database snapshots. |
| Logs and diagnostics | Read a bounded tail of the current worker log or clear it through a protected local write. Read backup status and snapshot names. Start one snapshot when backups are enabled. |
| Media | Read safe media metadata, owner-only source details, or ready viewer and llm image variants. Media reads are private to the local worker page even when other worker reads are exposed. |
| Sync and team knowledge | Read live cloud-sync status, inspect or recover local sync work, resolve sync conflicts, and read team status, boards, briefs, or shared search results. These routes keep credentials inside the worker. |
| Remote hook spool | Accept a versioned authenticated envelope. Durable entries enter the local spool and receive a receipt; live observer entries are consumed once and return 202 accepted. |
Request bodies are checked before they reach the data path. Invalid bodies use 400 with error: "ValidationError"; missing credentials use 401; an invalid key or missing scope uses 403; and a missing scoped record commonly uses 404 so the API does not reveal another tenant's data. Successful writes normally use 201, while reads and state changes use 200. Job retry and cancel reject invalid state changes with 409. Local worker routes use small status responses such as initialized, queued, skipped, accepted, or unknown_session to describe local processing state. Long corpus work can return one terminal result over JSON or server-sent events. Backup runs return 409 when another snapshot is active. Media uses bounded error codes for invalid, missing, not-ready, and unavailable content.
References: src/…/ServerV1PostgresRoutes.ts• L243-435 src/…/ServerV1PostgresRoutes.ts• L491-723 src/…/ServerV1PostgresRoutes.ts• L725-1045 src/…/ServerV1Routes.ts• L86-277 src/…/CorpusRoutes.ts• L148-285 src/…/DataRoutes.ts• L231-256 src/…/DataRoutes.ts• L464-580 src/…/SessionRoutes.ts• L621-661
Local worker controls
The local worker API provides control points for the desktop runtime rather than a tenant-scoped public API. Data, search, and context routes serve the viewer and local tools. Session, advisor, corpus, memory, and ingest routes accept capture or knowledge input. Work-state, work-view, setup, cloud-sync, recovery, backup, and team-knowledge routes let the local page or approved local tools inspect and change user-owned state or read remote shared data. Settings, logs, and media routes expose operational data under narrower local boundaries. The work-view surface also connects owner review with setup progress, focus sharing, and controlled continuation of the owner's conversations.
These routes do not use the server API-key middleware. Their safety depends on the worker host policy, loopback checks, trusted origins, route-specific write guards, and, when enabled, a local API token. The token is sent in X-Claude-Mem-Token or an equivalent local-token header. Read-only requests can also use one token query value for browser resources and event streams; writes must use the header. There is no cookie because a localhost cookie could cross ports. Only exact data-free UI shells and static assets can remain open so a page can load before it has read the token; a path prefix does not grant access.
A browser can read some local data from an allowed origin, but work-view, setup, sync-recovery, backup runs, imports, and other durable actions require the local machine and stricter request checks. Local browser writes also pass same-page checks. Destructive actions such as deletes, imports, log clearing, memory saves, corpus work, duplicate review, work-state writes, recovery transitions, conflict application, and other work review writes require the local page or an origin-less local client. Work-view file and deliverable reads also require the local viewer because they serve recorded files. Conversation continuation and shared-focus actions use the same boundary because they can start work or share owner data. The work-view routes use loopback and proxy-header checks for every route, require JSON same-page writes, and reject stale review or focus changes instead of silently overwriting newer owner state. Corpus work also stops when the client disconnects so a long provider task does not continue without a waiting caller.
Settings are intentionally a narrow local control surface. GET masks an explicit set of secrets and private contact values. POST accepts only approved settings, ignores unchanged environment echoes, and validates values before writing them. It cannot change data paths, bind hosts, executable paths, provider destinations, or the local API token. MCP enablement uses the same local-page write boundary. Dependency health is read-only. Backup status remains readable when backups are disabled, but a backup run requires the feature to be enabled and never acts on a request from another localhost page. Settings such as the file-read gate and work-view provider choices affect other local flows, so their route contract is part of the viewer configuration boundary; see smart file read gate.
References: src/…/middleware.ts• L36-81 src/…/middleware.ts• L100-112 src/…/middleware.ts• L151-200 src/…/middleware.ts• L238-328 src/…/SettingsRoutes.ts• L33-67 src/…/SettingsRoutes.ts• L244-301 src/…/SettingsRoutes.ts• L307-405 src/…/WorkViewRoutes.ts• L118-147 src/…/WorkViewRoutes.ts• L775-973
Search and context
The local search surface turns stored observations and sessions into lists, timelines, file-focused results, or compact context for a new agent turn. Context injection resolves the checkout's project scope, applies exclusion rules, and renders a local result without waiting for cloud sync; a background pull only improves a later request. Semantic context can return either short result indexes for later expansion or a bounded text block.
The route keeps project lists and paging values explicit. Invalid dates, limits, offsets, or project-list shapes fail before a search strategy can widen the read scope. Context rendering can also include work state and team-brief space, while cache generations and live invalidation prevent removed content from being written back as fresh context. Search telemetry records route, outcome, latency, and bounded retrieval facts without storing query text.
References: src/…/SearchRoutes.ts• L206-250 src/…/SearchRoutes.ts• L252-355 src/…/SearchRoutes.ts• L390-526 src/…/SearchRoutes.ts• L633-707 src/…/SearchRoutes.ts• L713-795
Work state and review
Work state is the small text contract used by agents and the viewer to keep project-scoped lists and open items. A write resolves the checkout to its project scope, rejects excluded projects and viewer-owned lists, and returns a plain-text summary. Work-view routes provide the richer owner surface for reviews, rules, focus areas, setup, usage, evidence, files, deliverables, conversation continuation, and shared focus pages.
Selected project and list pairs can add a local write check. The worker sends the current and proposed state to a configured command and accepts only a small valid allow or refuse answer. A missing guard file means no check. A bad file, failed command, timeout, excessive output, refusal, or change during the check prevents the write and returns 409.
The work-view boundary is stronger than the general local read boundary because it can expose files, start conversation work, and change owner decisions. Reads require the local machine, and browser writes require the viewer origin, same-site fetch metadata, and JSON. The route returns a full view or an overview and supports narrower request-detail and evidence reads. Recorded files and deliverables are served only through their stored identities and render in a sandboxed response. The worker serializes owner edits and uses revision or fingerprint checks where a stale browser view could overwrite a newer decision. Shared-page reads and writes stay in the worker so cloud credentials do not reach the page. Its event stream sends an initial view, later changes, setup state, and heartbeats, then stops its timers when no viewer remains.
References: src/…/WorkStateRoutes.ts• L31-49 src/…/WorkStateRoutes.ts• L62-169 src/…/work-state-write-guard.ts• L7-91 src/…/WorkViewRoutes.ts• L118-147 src/…/WorkViewRoutes.ts• L804-926
Corpus operations
The corpus API lets a local client save a named view of memory and use it for focused knowledge work. Build and rebuild select observations through filters. Prime, reprime, and query hand the saved corpus to a knowledge agent.
These operations can take minutes and are treated as one operation per corpus name. A client can request JSON or a server-sent event stream with heartbeats and one terminal result. Disconnecting the client aborts provider-bound work. A rebuild that would remove most of a non-trivial corpus requires explicit confirmation, so a changed filter cannot silently replace useful saved knowledge. The route accepts both snake_case and camelCase date names so local and MCP clients select the same saved range.
References: src/…/CorpusRoutes.ts• L38-65 src/…/CorpusRoutes.ts• L73-114 src/…/CorpusRoutes.ts• L148-285 src/…/CorpusRoutes.ts• L288-388
Viewer transport
The viewer routes serve the local work page, memory viewer, Observation TV, restart page, and a shared event stream. The stream gives connected pages an initial project catalog and processing state, then carries live changes such as new or deleted records.
The page files load lazily and cache only successful reads. If an update replaces the installed UI while the worker remains alive, the route reports a clear 503 page until the worker restarts; a later request can recover when the file returns. The restart page is inert until the user clicks. It checks both process identity and readiness so a still-running old worker is not mistaken for its successor. Sensitive pages refuse framing, and the stream stays same-origin unless the explicit remote read-only policy permits Observation TV reads.
References: src/…/ViewerRoutes.ts• L12-84 src/…/ViewerRoutes.ts• L87-213 src/…/ViewerRoutes.ts• L224-363 src/…/middleware.ts• L26-40 src/…/middleware.ts• L232-275
Remote hook intake
The remote hook endpoint lets a hook spool on another machine deliver capture records to the worker. It is enabled only when a worker ingest token is configured. The caller sends a fixed bearer token and a versioned envelope; the worker validates the envelope before either consuming a live observer event or placing a durable event in the local spool.
The endpoint returns a receipt with 202 accepted, not provider completion. Durable entries request a later drain. Live observer events reserve their receipt before ingest so redelivery cannot send the same fragment twice. This path is separate from normal local browser trust because it is an explicit machine-to-machine integration.
References: src/…/HookSpoolRoutes.ts• L20-70 src/…/shared.ts• L118-147 src/…/shared.ts• L192-478
Authentication and scope
API key authentication
API key middleware turns a request credential into an authentication context. That context carries the key identity, team, optional project, granted scopes, and auth mode. Route middleware checks the required scope before the handler runs, then route logic uses the team and project values to constrain every data action.
Clients should send the key in the canonical form:
Authorization: Bearer <api-key>
X-Api-Key: <api-key> is accepted as a fallback for clients that use that header shape. If both headers are present, the bearer value takes precedence. Read routes require memories:read, and write routes require memories:write; * remains an explicit broad grant rather than the default.
New keys use a salted, slow scrypt hash. The verifier compares hashes in constant time and keeps the older unsalted SHA-256 form only so existing keys continue to work. A successful legacy-key use upgrades its stored hash. Postgres verification narrows candidates by the non-secret key prefix and reuses a verified proof until the stored row changes, so revocation, expiry, scope edits, and re-hashing take effect on the next request. Verification work is bounded; an overloaded verification queue returns 503 with Retry-After rather than blocking the server.
The local SQLite path creates usable read and write memory scopes when a caller does not provide scopes. Key creation shows the raw value once, so a client must save it at creation time. Local worker session, memory, settings, media, sync-recovery, TeamBrain, and MCP-control routes are a separate local API surface and do not use this server API-key flow.
References: src/…/api-key-hash.ts• L17-39 src/…/api-key-hash.ts• L67-129 src/…/postgres-auth.ts• L51-140 src/…/postgres-auth.ts• L150-308 src/…/sqlite-api-key-service.ts• L41-164 src/…/ServerV1PostgresRoutes.ts• L157-245
Tenant and project scope
Team scope is the main data boundary. A project-scoped key narrows that boundary to one project, while a team-scoped key can work across the team's projects where the route allows it. The route layer checks the requested project before it reads or writes, and the Postgres queries also carry the team and project conditions.
This scope affects the API contract in two ways:
- A project-scoped key can read only its project and cannot create a new project.
- A request for a different team or project does not act on the record. Many Postgres routes return
404instead of confirming that the record exists elsewhere.
The local development bypass does not create a real tenant identity unless the runtime supplies one. It is allowed only when local-dev mode is enabled, the request is from loopback, the host is a loopback host, and no forwarded client headers are present. Deployable containers must use API-key auth rather than this bypass. Local worker routes rely on the local host, origin, and optional local-token policy instead.
References: src/…/ServerV1PostgresRoutes.ts• L491-601 src/…/ServerV1PostgresRoutes.ts• L1328-1376 src/…/request-auth-helpers.ts• L15-51 src/…/postgres-auth.ts• L66-114 src/…/middleware.ts• L151-169
Web authentication compatibility
Better Auth serves web sign-in and organization endpoints below /api/auth/*. It supports API-key and organization features for the web-facing auth system. The server-beta data routes still authenticate against their server API-key records, so web sessions and server API keys are not interchangeable by default.
This separation matters when a web user needs an integration key. The versioned key route can mint a read-only key for an already authorized team. The raw key is returned once with an MCP URL and a ready-to-paste connect command. A plain GET /v1/connect only returns a command with a placeholder and never creates a key.
References: src/…/auth.ts• L10-24 src/…/BetterAuthRoutes.ts• L27-41 src/…/ServerV1PostgresRoutes.ts• L196-246
Request handling
Request lifecycle
The deployable HTTP service applies shared request handling before route-specific checks. It parses JSON bodies, applies local CORS rules, can add hardening headers, logs a short request summary, assigns correlation data, and passes failures to the common error handler. Route handlers then validate the body, authenticate the caller where the route requires it, enforce scope, perform the data action, and return the known state.
The local worker adds a different network boundary. It checks trusted host names against DNS-rebinding attempts, permits only approved origins, refuses framing for every response, and limits foreign remote access to an explicit read-only allowlist. When local API-token mode is enabled, requests must also carry the configured token, except for exact open routes and data-free UI files. Read resources may carry the token in one query parameter when a browser API cannot set headers; writes must use the token header. Local browser writes also pass route-specific same-page checks. Work-view and setup writes additionally require a JSON request that is not marked as cross-site. Corpus, duplicate, advisor, work-state, import, backup, log-clear, and settings writes use the same-origin rule when they change durable local state. These controls protect the worker because its local routes do not have tenant API-key auth.
The deployable /v1 path assigns an X-Request-Id before authentication. An accepted inbound ID is reused for correlation; otherwise the service creates one. This ID is copied into logs, job metadata, and audit links. It is not an authentication value. Optional rate, quota, and usage guards run after authentication so they apply to the known key or team.
flowchart LR
A[Client request] --> B[Common HTTP middleware]
B --> C[Request ID for /v1]
C --> D[API key and scope check]
D --> E[Rate and quota guards]
E --> F[Body or query validation]
F --> G[Team and project check]
G --> H[Route action]
H --> I[Audit and response]
D --> J[401 or 403]
E --> K[429 or 402]
F --> L[400 validation error]
G --> M[403 or scoped 404]
H --> N[Common error response]
References: src/…/Server.ts• L125-134 src/…/middleware.ts• L26-81 src/…/middleware.ts• L100-200 src/…/middleware.ts• L238-328 src/…/middleware.ts• L492-529 src/…/ServerV1PostgresRoutes.ts• L162-196 src/…/request-id.ts• L6-40 src/…/ErrorHandler.ts• L36-65
Validation and response behavior
Validation protects the API contract at the edge and keeps invalid data out of the shared event and memory paths. Event and session shapes are shared with clients through schema definitions, while route-specific query values control options such as search limits, generation, waiting, and job filters. Local worker routes validate session, memory, media, work-view, import, corpus, duplicate-review, work-state, and settings bodies before they start local work.
Session initialization filters internal or private prompt content, bounds oversized prompts, and suppresses recent duplicate prompts before it starts observer work. Observation ingest applies project, tool, subagent, and privacy filters before it stores tool-use data or queues provider work. Media capture occurs only after those gates and stores bounded references rather than raw image bodies in the memory path. Advisor ingest accepts durable transcript records and makes replayed tool-use IDs harmless.
The local worker's data routes accept explicit repeated path values where paths can contain commas. Observation and raw tool-use disclosure are ID-based and bounded. Search rejects malformed dates, pagination, and project lists before a strategy runs. Settings validation checks only changed values, preserves masked secrets, filters environment-only echoes, and rejects values that could alter the worker's storage or network boundary. Work-view validation limits owner actions to known states and identities. Corpus validation accepts both date naming styles used by local and MCP clients.
The API reports the state that it knows instead of claiming that background work completed. Event responses identify whether generation was enqueued, remains queued for later reconciliation, or was not created because generation was disabled. Local worker writes return counts or handoff states. Imports report stored, skipped, and rejected rows. Media reports media_not_ready until bytes are safe to read. Remote spool intake reports acceptance and a receipt, not provider completion. A disconnected corpus stream ends without a false terminal success.
References: src/…/ServerV1PostgresRoutes.ts• L78-120 src/…/ServerV1PostgresRoutes.ts• L326-423 src/…/CorpusRoutes.ts• L38-65 src/…/CorpusRoutes.ts• L210-285 src/…/DataRoutes.ts• L79-126 src/…/DataRoutes.ts• L846-915 src/…/SessionRoutes.ts• L694-827 src/…/WorkViewRoutes.ts• L111-210 src/…/shared.ts• L192-477
Request limits and usage controls
Paid-readiness controls sit after authentication so they apply to a known key or team. They are off unless configured. When enabled, request rate limits apply per API key, request quotas apply per team and month, token quotas apply to writes, and request metering records one usage event without delaying the response.
| Control | Boundary | Response or effect |
|---|---|---|
| Request rate limit | API key and fixed time window | 429 with Retry-After and rate-limit headers |
| Monthly request cap | Team and UTC calendar month | 402 quota_exceeded |
| Monthly token cap | Team and write requests | 402 quota_exceeded; reads remain available |
| Request metering | Authenticated team request | Fire-and-forget request usage record |
The guards fail open when their storage check fails. This keeps a metering or limit-store outage from taking down the API, but it also means operators must monitor the control path separately.
References: src/…/ServerV1PostgresRoutes.ts• L168-195 src/…/rate-limit.ts• L23-101 src/…/usage-metering.ts• L13-32
Event and session flows
Event ingestion and generation
Event ingestion is the main bridge between an HTTP client and background observation generation. The API first stores the event and its generation record together, then publishes the background job after the database transaction. A separate worker can consume that job without making the HTTP request wait for a provider call. See Observation generation and provider runtime for the downstream generation path.
The following flow shows the contract for a normal event request and for wait=true.
sequenceDiagram
participant C as Client
participant A as /v1/events
participant P as Postgres
participant Q as Job queue
participant W as Generation worker
C->>A: POST event
A->>P: Store event and outbox job
P-->>A: Commit event and job state
A->>Q: Publish generation job
A-->>C: 201 event and job status
Q->>W: Deliver job
W->>P: Store observations and update job
opt wait=true
A->>P: Poll job status up to 30 seconds
A-->>C: 201 event and terminal or current job status
end
POST /v1/events/batch validates the whole batch before the atomic insert. The batch accepts one to 500 events. If the queue is unavailable, the event and outbox state remain visible as queued rather than being reported as generated. generate=false records the event but skips the generation job. Session links can resolve from a content session identity when the server session ID is not present.
References: src/…/ServerV1PostgresRoutes.ts• L243-423 src/…/IngestEventsService.ts• L89-247 src/…/ServerV1PostgresRoutes.ts• L1200-1325
Session lifecycle
Sessions give events a conversation-level boundary and let the system produce a summary when work ends. A client starts or finds a session, sends events linked to that session, and ends it when the session is complete. The end operation is idempotent and returns the summary generation job when one is created.
The deployable API makes session start idempotent when a client supplies an external session identity with its platform source. This prevents concurrent or repeated starts from creating parallel server sessions. The local worker follows the same broad lifecycle for hook clients. Session initialization records the prompt and decides whether to inject context. It ignores internal protocol input, removes private memory tags, limits very large prompts, and avoids saving a recent duplicate. A native prompt identity can make intentional repeated text distinct and detects reuse with different text. Observation calls add tool activity to the session. Summarize calls queue the final assistant content, while session-end calls request wrap-up and report whether the session is known. The worker then starts or resumes the selected provider and reports a local handoff instead of waiting for the full provider response.
The same session-end service is used by canonical and compatibility paths. Shared local ingest keeps durable handoff separate from provider completion, so a durable caller can retry only work that was not accepted. The ingest path also keeps privacy, project exclusion, replay, media, deliverables, advisor-call, and tool-use rules in one place for HTTP and spool callers. Per-session start locking prevents concurrent requests from starting two generators for one session.
References: src/…/ServerV1PostgresRoutes.ts• L725-874 src/…/EndSessionService.ts• L53-153 src/…/SessionRoutes.ts• L621-661 src/…/SessionRoutes.ts• L694-827 src/…/shared.ts• L192-477 src/…/shared.ts• L506-716
Manual memory writes
Manual memory writes provide a direct path for a client that already has memory text and does not need provider generation. The versioned server route stores an observation without creating an outbox job. An optional generationKey makes that write idempotent: a repeated key returns the original observation and marks the response as existing. Both the server and worker paths return the new observation identity so the caller can track the saved memory.
The local worker write also skips excluded checkouts before saving. It nudges cloud sync and live indexes asynchronously. Memory-file ingest follows the same local write goal: it stores native memory files directly, deduplicates exact replays across current and legacy content forms, preserves file time, and returns a report for stored, duplicate, skipped, and failed items.
References: src/…/ServerV1PostgresRoutes.ts• L876-976 src/…/MemoryRoutes.ts• L14-57 src/…/MemoryIngestRoutes.ts• L17-143
Compatibility layers
Legacy session adapters
The legacy routes preserve the request and response shapes expected by older worker clients while translating their meaning into the current event and job model. They require a project-scoped write key because the old payload does not carry the project identity needed by the tenant boundary.
| Legacy route | Translation | Compatibility behavior |
|---|---|---|
POST /api/sessions/observations | Tool-use payload to an agent event | Creates or finds the server session, queues event generation, and returns status: "queued" with event and job IDs. |
POST /api/sessions/summarize | Content session ID to a session end | Ends the matching server session and queues a summary. Calls from subagent contexts return status: "skipped" to preserve old behavior. |
These adapters are not a second data path. They call the same ingestion and session-end services as the canonical routes, so queue state, privacy filters, and idempotency rules stay consistent during client migration.
References: src/…/SessionsObservationsAdapter.ts• L3-19 src/…/SessionsObservationsAdapter.ts• L57-167 src/…/SessionsSummarizeAdapter.ts• L3-13 src/…/SessionsSummarizeAdapter.ts• L43-131
Local worker session bridge
The local worker session routes are the bridge between hook clients and the in-process observer. They accept session IDs, tool observations, prompts, and end signals in the shapes used by local integrations. The bridge removes private or internal protocol content, avoids duplicate prompts, captures media only after privacy checks, and returns a small status that tells the caller whether work was stored, skipped, or queued. Shared ingest logic also records durable advisor calls, deliverables, agent lifecycle state, and replay-safe tool-use receipts for related local clients.
Accepted session initialization returns the local session ID, prompt number, context state, and initialized status when the caller uses the newer native prompt contract. Observation and summary requests return queued when they enter local work, while session-end requests return accepted or unknown_session. The bridge starts or resumes a provider when needed, but callers should treat queued as acceptance of work rather than proof that an observation or summary is complete.
References: src/…/SessionRoutes.ts• L621-661 src/…/SessionRoutes.ts• L694-1051 src/…/shared.ts• L192-478 src/…/shared.ts• L506-716
Remote hook spool bridge
The remote hook spool bridge preserves a small, retry-safe contract between a remote capture process and the local worker. It uses a dedicated ingest token rather than the local browser trust model. The receipt is the caller's durable proof of acceptance; the provider worker may run later or may skip a filtered event.
Live observer entries use receipt reservation and are ingested once. Other entries enter the spool and wake its drain. A protocol version mismatch or invalid envelope is a client error, while a missing token disables the integration with 503.
References: src/…/HookSpoolRoutes.ts• L11-39 src/…/HookSpoolRoutes.ts• L41-70 src/…/shared.ts• L118-147
Remote MCP recall
The /v1/mcp route exposes the read side of the API through streamable HTTP for Claude Code and other MCP clients. It uses the same API-key, team, project, and audit boundaries as REST search. The transport is stateless, and the available tools are limited to search, context, and recent recall; a pasted recall link cannot write memory. The shared read path is also relevant to the interactive viewer client.
Clients can obtain the connection shape from /v1/connect or mint a read-only key with POST /v1/keys. The MCP URL can use the configured public URL or the request host, which lets a proxy present a stable external address.
References: src/…/ServerV1PostgresRoutes.ts• L1003-1107 src/…/ServerV1PostgresRoutes.ts• L191-246 docs/api.md• L55-77 docs/api.md• L94-119
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the SQLite and Postgres route contracts aligned when changing shared
/v1behavior. Local clients can use either runtime. - Preserve the team and optional project scope in new reads, writes, job lookups, and deletion paths. A route that checks only the URL project can cross a tenant boundary.
- Keep
AuthorizationandX-Api-Keyparsing behavior aligned in both auth middleware paths. Client bundles depend on the fallback header. - When changing API-key storage, keep the salted and legacy verification paths compatible. Preserve prefix lookup, first-use legacy upgrades, constant-time comparison, cache invalidation on row changes, and the bounded verification queue.
- When changing event or session request fields, update the canonical schemas, both legacy translators, and the local worker session bridge together.
- When changing local session payloads or status values, keep the four worker session endpoints aligned with their validation schemas and caller expectations for
initialized,queued,skipped,accepted, andunknown_session. - When adding a route that returns generation state, preserve the distinction between
enqueued,queued_only, andskipped. These values tell clients whether they must poll or wait for reconciliation. - Keep request IDs as correlation data only. Do not use an inbound
X-Request-Idas an identity or permission signal. - Treat
/v1/mcpand REST search as one read contract. Changes to search scope or context packing affect both integration types. - When changing web auth or API-key creation, check the boundary between Better Auth records and the server API-key records. They are not automatically the same credential store.
- When changing local worker middleware, preserve the trusted-host check, origin rules, framing protection on every response, remote read-only allowlist, exact static-path exceptions, and local-token exceptions for UI shells and read resources. A new route must not become reachable through a foreign page or remote read allowlist by accident.
- When changing local-token mode, keep header precedence, the single read-only query token, no-cookie behavior, exact open-route matching, and static UI bootstrap aligned with the viewer and restart page.
- When changing backup or restore behavior, keep status and list available for disabled installs, keep snapshot runs serialized, and preserve the CLI-and-restart restore flow.
- When changing corpus work, preserve the JSON/SSE terminal contract, disconnect abort, one-operation-per-name rule, date aliases, and destructive-shrink confirmation.
- When changing remote spool intake, preserve the fixed bearer-token check, protocol version, receipt semantics, live-event reservation, body limit, and
202acceptance response. - When changing search or context routes, preserve explicit project resolution, bounded pagination, date validation, excluded-checkout behavior, and cache invalidation so a request cannot widen its read scope or restore deleted context.
- When changing session ingest, preserve the order of privacy, project, agent, tool, media, and replay gates before provider handoff. Keep durable handoff status separate from provider completion.
- When changing imports or deletes, preserve cloud-sync safety, vector-index cleanup, live viewer invalidation, and per-row rejection or refusal reporting.
- When changing settings output or writes, keep the explicit secret and private-data allowlist, masking behavior for strings and key pools, environment-echo filtering, file-only setting boundary, and HTTP write whitelist aligned. The settings routes have no API-key middleware.
- When changing media responses, preserve the owner-only read rule, generic metadata projection, bounded status batches, no-cache behavior, variant readiness checks, and deletion recheck.
- When changing work state or work-view writes, keep agent-owned lists separate from owner-managed rules, focus, and review state. Preserve checkout scope, revision checks, local viewer origin checks, JSON and same-site requirements, and the stored-identity checks for files and deliverables.
- When changing the work-state write guard, preserve its project/list scope match, bounded command configuration, two-second timeout, small JSON answer, refusal status, and re-read race check.
- When changing memory-file ingest, preserve the allowed source boundary, direct-store behavior, exact replay deduplication, file-time preservation, per-item report, and cloud-sync notification.
- When changing viewer pages or restart behavior, preserve lazy UI recovery, frame protection, token forwarding, process identity checks, and readiness polling.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Missing API key | Request stops with 401 | Send Authorization: Bearer <key> or the supported X-Api-Key header. |
| Key is revoked, expired, or lacks the route scope | Request stops with 403 | Use an active key with memories:read for reads and memories:write for writes. |
| API-key verification queue is full | Request stops with 503 and a short retry hint | Retry after Retry-After; reduce invalid-key bursts. |
| Project-scoped key addresses another project | No cross-project access; the route returns 403 or scoped 404 | Use the project bound to the key or use an approved team-scoped key. |
| Local API token is missing, repeated, or invalid | Worker request stops with 401 | Send the token in the local token header. Use one query token only for supported reads. |
| Worker receives an untrusted Host or foreign origin | The request is rejected before local data is served | Use the worker's trusted host and the viewer's own origin. |
| A remote worker caller uses a non-read method or a non-allowlisted path | The request is denied even with a remote token | Use only the documented read-only remote paths and methods. |
| Generation queue is unavailable after event storage | Event is stored and the job remains queued; no false success is reported | Poll the job and allow startup reconciliation or operator action to publish it. |
| Remote spool token is missing or wrong | Intake is disabled with 503 or rejected with 401 | Configure the worker ingest token and send the exact bearer form. |
| Remote spool envelope has an unknown version or invalid entry | Intake returns 400; no receipt is issued | Use the current protocol version and envelope schema. |
| A remote live spool event is redelivered | The receipt is accepted without sending the observer fragment twice | Keep the receipt and let the worker's consumed-marker store deduplicate it. |
| Search receives an invalid project list, date, limit, or offset | The route returns 400 before the search can widen its scope | Send named project keys and bounded, valid query values. |
| A context request names an excluded checkout | The route returns empty context and does not expose memory | Use an included checkout or change the exclusion setting. |
| A local memory save comes from a foreign localhost origin | The route returns 403 and no memory is created | Use the local viewer origin or an origin-less local client. |
| Ingest receives private, internal, excluded, duplicate, or filtered tool data | The route returns skipped and does not queue provider work | Treat the returned reason as an intentional capture decision. |
| A local session prompt exceeds the input size limit | The prompt is truncated before it is stored or sent to the observer | Keep prompts below the 256 KiB boundary and do not depend on truncated text for exact replay. |
| A native prompt identity is reused with different text | Session init returns 409 and does not accept the conflicting turn | Keep native prompt IDs unique within the platform and content session. |
| A local session ends before it is known to the worker | The route returns unknown_session and no wrap-up is requested | Initialize the session first and retain the platform source used for lookup. |
| A settings viewer posts a masked secret as a replacement | The stored secret can be lost or changed unexpectedly | Preserve a secret only when the submitted value exactly matches the mask of the stored value. |
| A local settings endpoint is exposed on an unsafe host | An unauthenticated local control API becomes reachable to other clients | Keep the worker on loopback unless the documented local display or container bind is required. |
| A settings write attempts to change a file-only or network-bound setting | The value is rejected or ignored, preventing a new storage or bind boundary | Use the supported settings UI for approved values and change file-only values through the documented local configuration. |
| A backup run is requested while backups are disabled | The route returns 400 and no snapshot is made | Enable backups and restart the worker before starting a run. |
| A second backup run starts while the first is active | The route returns 409 and leaves the active snapshot alone | Wait for the current snapshot to finish. |
| A corpus operation uses a name already in progress | The route returns 409 and does not interleave corpus files | Wait for the named operation to finish. |
| A corpus client disconnects during provider work | The request ends and the provider work is aborted | Reconnect and retry when the caller still needs the result. |
| A corpus rebuild would remove most saved observations | The old corpus remains and the route returns 409 | Review the filter and repeat with force=true only when the shrink is intended. |
| A log request asks for an invalid or excessive line count | The route rejects it or caps the returned tail | Use a non-negative integer and treat the result as a bounded tail. |
| An import contains invalid or unbindable rows | Valid rows can import, while rejected rows are reported in the response | Inspect the per-kind rejection report before treating the import as complete. |
| A session delete finds active work or remote children | The route returns 409 and avoids a cascading unsynced delete | End the session first and delete synced children on their owning device. |
| A work-view write is cross-site, not JSON, or stale | The route returns 403 or 409; owner state is not overwritten | Write from the local viewer with the current revision or fingerprint. |
| A configured work-state write guard refuses, fails, times out, or sees changed state | The write returns 409 and no new work-state row is appended | Repair the guard command or read current state before retrying. |
| A recorded file or deliverable is requested from a foreign page or mismatched filename | The route returns 403 or 404 and no file is served | Open the file from the local work viewer through its recorded identity. |
| Media is requested before conversion or replica resolution finishes | The route returns 409 media_not_ready or a pending status | Poll the bounded status route and retry the ready variant. |
| A memory ingest source is outside the allowed projects directory or the request comes from another localhost origin | The route returns 400 or 403; no full-tree import starts | Use an allowed source and the local viewer origin or an origin-less local client. |
| A viewer loads while its installed UI files are missing | The route returns a no-store 503 recovery page | Restart the worker after the install is complete. |
| A restart page sees the old worker's healthy response | It does not report a completed restart | Wait for a different process identity and a ready successor. |
Key files
| File | Why to read it |
|---|---|
| src/…/ServerV1PostgresRoutes.ts | Main deployable /v1 contract for events, sessions, memories, search, jobs, MCP, usage, deletion, and manual-write idempotency. |
| src/…/ServerV1Routes.ts | SQLite-backed local version of the core route contract, including searchable-memory write guards and PATCH semantics. |
| src/…/api-key-hash.ts | Shared API-key hashing, legacy verification, timing-safe comparison, and bounded verification work. |
| src/…/postgres-auth.ts | Team, project, scope, expiry, revocation, cache, and local-dev rules for the deployable runtime. |
| src/…/sqlite-api-key-service.ts | Local key creation, default scopes, verification, revocation, and legacy-key upgrade behavior. |
| src/…/middleware.ts | Local worker host, origin, framing, remote read-only, CORS, exact UI exceptions, and optional local-token boundaries. |
| src/…/ViewerRoutes.ts | Local UI shells, health, restart handoff, lazy UI loading, and the viewer/Observation TV event stream. |
| src/…/SessionRoutes.ts | Local hook session contract, native prompt handling, and bridge into the in-process observer and provider flow. |
| src/…/HookSpoolRoutes.ts | Remote hook authentication, protocol validation, receipt handling, and durable versus live intake. |
| src/…/shared.ts | Shared local ingestion rules for privacy, filtering, media, deliverables, advisor calls, tool-use indexing, replay, and provider handoff. |
| src/…/MemoryIngestRoutes.ts | Direct memory-file import, source checks, exact replay deduplication, and import reporting. |
| src/…/DataRoutes.ts | Viewer data feeds, progressive tool-use disclosure, sync-safe deletion, imports, project merging, and processing state. |
| src/…/SearchRoutes.ts | Local search, timeline, semantic context, context injection, project scoping, and cache-safe rendering. |
| src/…/CorpusRoutes.ts | Saved corpus lifecycle, long-operation transport, cancellation, and rebuild safety. |
| src/…/BackupRoutes.ts | Local snapshot status, snapshot listing, serialized runs, and restore-result reporting. |
| src/…/LogsRoutes.ts | Bounded log reads and protected local log clearing. |
| src/…/MediaRoutes.ts | Private media metadata, readiness, provenance, variant reads, and bounded media errors. |
| src/…/SettingsRoutes.ts | Local settings reads and writes, explicit secret masking, validation, file-only boundaries, dependency health, and MCP controls. |
| src/…/WorkStateRoutes.ts | Agent work-state reads and writes with project resolution and owner-list protections. |
| src/…/work-state-write-guard.ts | Optional local command check for selected work-state writes and its bounded refusal contract. |
| src/…/WorkViewRoutes.ts | Local work review, setup state, focus sharing, live events, evidence, deliverables, conversation continuation, and owner-only writes. |
| src/…/Server.ts | Shared deployable HTTP middleware, runtime routes, and final error handling. |