Platform and server

Every PocketContext application runs on a single Go binary, pocketcontext, that embeds PocketBase for SQLite storage, authentication, and REST record changes. PocketContext adds a read-only SQL endpoint, /api/context/query, so an assistant can join and aggregate data directly. Writes still go through the records API, where the application's rules and hooks run.

An application is a folder of rules the server loads, not a second kind of server. In production each application is its own process, its own database, and its own Google client. The file POCKETCONTEXT_VERSION in that folder is the server commit the application was tested with. Building a newer server binary does not upgrade the application's tables.

flowchart TD
  migrations["pb_migrations — tables and rules"]
  hooks["pb_hooks — extra checks"]
  config["pocketcontext.json — what SQL may see"]
  skill["skill and CLI"]
  ui["browser pages"]
  pb["PocketBase — login, records, files"]
  sql["SQL reader — questions only"]
  snap["filtered copy — only this person's rows"]
  data["pb_data — the database on disk"]

  migrations --> pb
  hooks --> pb
  config --> sql
  skill --> sql
  skill --> pb
  ui --> pb
  pb --> data
  sql --> data
  sql --> snap
  snap --> data

Read with SQL, write through the API

sequenceDiagram
  participant A as Assistant
  participant R as /api/context/query
  participant W as /api/collections/.../records
  participant D as Database

  A->>R: one SELECT, with a bearer token
  R->>D: read-only connection
  D-->>A: columns, rows, truncated?

  A->>W: POST or PATCH a record
  W->>D: PocketBase rules and hooks
  D-->>A: saved record

SQL accepts one statement. Joins, aggregates, and ordinary SQLite functions are allowed. Writes, schema changes, transactions, and PRAGMA are refused. The default caps are 2 seconds, 500 rows, and 1 MiB of results. When the row cap is hit, the response includes truncated: true, so the answer is incomplete.

The bearer token comes from the collection named in authCollection, often users or agents. A superuser token does not bypass SQL.

Shared workspace or a private copy

The application decides which rows an assistant may see. The server does not invent that policy.

flowchart TD
  login[Signed-in account]
  login --> mode{How this app is configured}
  mode -->|shared workspace| all[Every account can read the configured columns]
  mode -->|filtered snapshots| copy[A private copy of only this person's rows]
  all --> query[The SQL query runs]
  copy --> query

TaskContext, DealContext, RaiseContext, and LinkContext are shared workspaces: teammates see the same rows. PeopleContext, AccountContext, WikiContext, NotifyContext, and ChatContext filter, each with its own rule. With filtered snapshots, each query runs against a separate database that holds only the rows that account may see. The copy is reused until the real database commits a change. Policies that depend on the clock are not reused.

Search, traces, and the files on disk

Some applications turn on POST /api/context/search. The assistant sends an index name and text, not SQL, and full-text tables stay off the SQL endpoint. Applications that use filtered snapshots build a private index from that person's rows.

Tracing is off unless pocketcontext.json asks for it. A finished request can be written as one JSON line: route, status, user id, duration, and named steps such as prepare, execute, and scan. The line does not include passwords, request bodies, or query results. SQL text is optional and capped, because a query can contain private values. The server does not send that line to ObserveContext. The application's own client uploads it later. See Observe.

pb_data holds the database and credentials and stays out of Git. Back it up before an upgrade. PocketBase is still pre-1.0, so read its upgrade notes before moving versions. A superuser can freeze writes through the maintenance API without stopping the process. Reads continue, and new changes wait until the freeze lifts. An application has to adopt that contract before using it for a migration.

Installers for Linux (amd64 and arm64) and macOS 15 or later on Apple Silicon are in the server guide.

Tools beside the server