@inixiative/archive 0.5.1 → 0.7.0

package/README.md

@@ -4,79 +4,65 @@ MIT-licensed, local-first session storage for Claude Code, Codex and Foundry. Ru
 
 ## What runs today
 
-- Public transcript extraction, exact-project collection, immutable SQLite revisions, local lexical search and lossless text chunks.
-- A standalone authenticated HTTP server, Docker image, persistent Compose deployment, Railway configuration and a Render blueprint.
+- Public transcript extraction, exact-project collection, immutable revisions in Postgres (pgvector and pg_trgm enabled), lexical search and lossless text chunks.
+- An authenticated HTTP server, published image, Compose deployment with its own Postgres, Railway configuration and a Render blueprint.
+- An HTTP client the CLI, collectors and Foundry write through; only the server holds the database.
 - Multiple explicit destinations, durable publication receipts/outbox, conflict detection and retry after interruption.
-- Native Foundry capture and context retrieval; Kingdom's existing Archives browser, ownership and sharing APIs.
 
-This is an initial pilot, not a general multi-user standalone hosting service. Each standalone deployment is one ownership boundary with one access token. Kingdom supplies account-based sharing. Use distinct storage and credentials for personal and organization archives.
+Each deployment is one ownership boundary with one access token. Kingdom supplies account-based sharing. Use distinct deployments and credentials for personal and organization archives.
 
 ## Local setup
 
-Install Bun 1.4.2 or later, then install the published CLI:
+Run one Archive per machine with Docker Compose. It runs the published image with its own Postgres, on the `archive` block of the shared port registry (`bunx @inixiative/config ports archive`): HTTP on loopback 4700, Postgres on loopback 6132.
 
 ```sh
 bun add --global @inixiative/archive
-archive init
-archive serve
+archive up      # creates ~/.local/share/archive/server.token, then docker compose up
+archive down
 ```
 
-For development from source:
+`up` runs the `compose.yaml` that ships in the package (project `archive`) with `ARCHIVE_DATA_DIR` set to the archive home and the server token from its `server.token`. Postgres data lives in `$ARCHIVE_DATA_DIR/postgres` and the server's destinations in `$ARCHIVE_DATA_DIR/config`, so both survive rebuilds and volume prunes. Pin a version with `ARCHIVE_VERSION`; build from a checkout with `docker compose -f compose.yaml -f compose.build.yaml up -d --build`.
 
-```sh
-bun install
-bun run archive init
-bun run archive serve
-```
-
-`init` creates a local database and a private `server.token` under `~/.local/share/archive`. It prints the token's file path, never its value. `serve` binds to loopback port 4411. The server requires bearer authentication for data endpoints; `/health` has no session data.
+The server applies its schema migrations on start and requires bearer authentication for data endpoints; `/health` has no session data. Every other command talks to it over HTTP at `--url` (default `http://127.0.0.1:4700`) with the token in `--token-file` (default `~/.local/share/archive/server.token`) or `ARCHIVE_TOKEN`:
 
 ```sh
-bun run archive preview --directory /path/to/history --source codex
-bun run archive import --file /path/to/session.jsonl --source codex --project-id inixiative --tag coding
-bun run archive collect --directory /path/to/history --source codex --project-root /exact/session/cwd --project-id inixiative --watch
-bun run archive list
-bun run archive search --query 'migration'
+archive preview --directory /path/to/history --source codex
+archive import --file /path/to/session.jsonl --source codex --project-id inixiative --tag coding
+archive collect --directory /path/to/history --source codex --project-root /exact/session/cwd --project-id inixiative --watch
+archive list
+archive search --query 'migration'
 ```
 
-Use `--source claude-code` for Claude histories. Collection matches the exact working-directory metadata recorded by the provider. Repeat `--project-root` to map several checkouts to one project; `--worktrees` also accepts every current git worktree of each root, re-read on each scan. Nested checkouts are separate mappings. Unknown directories, symlinks and sessions without usable metadata are skipped. Incomplete or changing files remain at source and retry on the next scan. The initial collector rescans files every 30 seconds; it deduplicates normalized content rather than maintaining byte-offset ingestion cursors. It retains prior manually assigned tags. It does not upload: run sync separately.
+Use `--source claude-code` for Claude histories. Collection matches the exact working-directory metadata recorded by the provider. Repeat `--project-root` to map several checkouts to one project; `--worktrees` also accepts every current git worktree of each root, re-read on each scan. Nested checkouts are separate mappings. Unknown directories, symlinks and sessions without usable metadata are skipped. Incomplete or changing files remain at source and retry on the next scan. The collector rescans files every 30 seconds; it deduplicates normalized content rather than maintaining byte-offset ingestion cursors. A watching collector waits out a server that is still starting.
+
+To run the server without Docker, point `DATABASE_URL` at a Postgres with the `vector` and `pg_trgm` extensions available and run `archive serve [--port 4700] [--sync]`. Set `ARCHIVE_DEBUG=1` to see the underlying error when a command fails.
 
 ## Connect to BYO hosting
 
-Deploy the included Dockerfile with a persistent volume mounted at `/data`, HTTPS, and a unique `ARCHIVE_SERVER_TOKEN` of at least 32 characters. Compose bind-mounts `./data` (or `ARCHIVE_DATA_DIR`) at `/data`, so the store survives rebuilds, `down -v` and volume prunes, and binds only to loopback on port 4411 (or `ARCHIVE_PORT`); put an HTTPS reverse proxy in front for remote use. Railway needs a `/data` volume. The Render blueprint provisions a dedicated disk and generated token.
+Every deployment runs the published image `ghcr.io/inixiative/archive` (tags: version, `latest`, commit SHA), built from main for amd64 and arm64, with `DATABASE_URL` pointing at Postgres 15 or later with pgvector, HTTPS in front, and a unique `ARCHIVE_SERVER_TOKEN` of at least 32 characters. It needs nothing else. The Render blueprint provisions the database, the image and a generated token together. On Railway, add a pgvector Postgres service and the image as a service with `DATABASE_URL` referencing it (`railway.json` builds the Dockerfile when deploying from the repository instead).
 
-Place the destination's token in a private file (`chmod 600`, owned by you) or an environment variable, then run:
+The local Archive publishes onward to destinations. Place the destination's token in a private file under the server's config directory (`chmod 600`, owned by you) or an environment variable, then run:
 
 ```sh
-bun run archive connect --url https://your-archive.example --project-id inixiative --token-file ~/.local/share/archive/credentials/inixiative.token
-bun run archive routes
-bun run archive sync
-bun run archive sync --watch
-bun run archive search --remote --query 'migration'
+archive connect --home ~/.local/share/archive/config --url https://your-archive.example --project-id inixiative --token-file ~/.local/share/archive/config/credentials/inixiative.token
+archive search --remote --home ~/.local/share/archive/config --query 'migration'
 ```
 
-`setup` is an alias for `connect`. Setup verifies access before saving configuration and does not upload. The URL locates the server; the token grants access. Configuration stores only the token file path (`tokenFile`) or environment variable name (`--token-env`, `tokenEnv`), never the token. A token file is read on every request, so rotating it needs no restart; symlinks and files readable by group or others are refused. An environment variable must be set in the sync process environment. Redirects are refused; only HTTPS or loopback HTTP is allowed.
-
-`--home PATH`, `--store FILE` and `--config FILE` support custom paths. Keep the database with its source UUID when moving machines. Back up the entire database; a new store creates a new source identity.
+`setup` is an alias for `connect`. Setup verifies access before saving `destinations.json` and does not upload; the Compose server (`serve --sync`) reads it and publishes every 30 seconds. `sync` and `routes` run the same publication, or preview it, once against `DATABASE_URL`. The URL locates the server; the token grants access. Configuration stores only the token file path (`tokenFile`) or environment variable name (`--token-env`, `tokenEnv`), never the token. A token file is read on every request, so rotating it needs no restart; symlinks and files readable by group or others are refused. Redirects are refused; only HTTPS or loopback HTTP is allowed.
 
 ## Always-on local archiving
 
-`archive agents` declares long-running agents in `~/.local/share/archive/agents.json` and installs them as launchd agents (macOS) or systemd user units (Linux):
+`archive agents` declares collectors in `~/.local/share/archive/agents.json` and installs them as launchd agents (macOS) or systemd user units (Linux). They run on the host, where the session histories are, and write to the local Archive server:
 
 ```sh
-archive init
-archive connect --url https://your-archive.example --project-id inixiative --token-file ~/.local/share/archive/credentials/inixiative.token
 archive agents add-collector --name claude-code.inixiative --source claude-code --project-id inixiative --project-root ~/code/inixiative --worktrees
 archive agents add-collector --name codex.inixiative --source codex --project-id inixiative --project-root ~/code/inixiative --worktrees
-archive agents serve on
-archive agents sync on
+archive agents server --url http://127.0.0.1:4700   # only when not the default
 archive agents install
 archive agents status
 ```
 
-`add-collector` upserts by `--name` (lowercase letters, digits, `.` and `-`); `--directory` defaults to `~/.claude/projects` or `~/.codex/sessions`, and `--project-root`, `--worktrees` and `--atlas` behave as for `collect`. `remove-collector --name N`, `serve on|off [--port P]` and `sync on|off` edit the same file. `install` writes one unit per agent: `com.inixiative.archive.local` (serve), `com.inixiative.archive.sync` (`sync --watch`) and `com.inixiative.archive.collect.<name>`. Each runs the current Bun with this package's own `src/cli.ts`, restarts on exit (30 second throttle), works in the archive home and logs to `logs/<label>.{out,err}.log` there. Re-running `install` reloads only changed or stopped units and removes Archive units no longer declared; other launchd agents are untouched. `uninstall` removes every Archive unit; `status` reports each unit's load state, PID and last log entry. One archive home per user account: units are named by agent, not by home. Sync reads destination token files itself, so no wrapper script is needed. Re-run `install` after upgrading the package if its install path changes.
-
-Docker Compose is the alternative for the server: `docker compose up -d` bind-mounts `./data` (or `ARCHIVE_DATA_DIR`) at `/data` and binds loopback port 4411. It is a separate store, so connect it as a destination and let the `sync` agent publish to it; do not bind-mount the store the host agents are writing, since SQLite locking across the Docker VM boundary is unreliable. Collectors run on the host, where the session histories are.
+`add-collector` upserts by `--name` (lowercase letters, digits, `.` and `-`); `--directory` defaults to `~/.claude/projects` or `~/.codex/sessions`, and `--project-root`, `--worktrees` and `--atlas` behave as for `collect`. `remove-collector --name N` and `server --url URL` edit the same file. `install` writes one unit per collector, `com.inixiative.archive.collect.<name>`. Each runs the current Bun with this package's own `src/cli.ts`, restarts on exit (30 second throttle), works in the archive home and logs to `logs/<label>.{out,err}.log` there. Re-running `install` reloads only changed or stopped units and removes Archive units no longer declared (including the retired `local` and `sync` units); other launchd agents are untouched. `uninstall` removes every Archive unit; `status` reports each unit's load state, PID and last log entry. Re-run `install` after upgrading the package if its install path changes.
 
 `@inixiative/archive/agents` exports the pure pieces for integrations: `agentsConfigSchema`, `agentUnits`, `renderPlist`, `renderSystemdUnit` and `planAgents`, plus `installAgents`, `uninstallAgents` and `agentStatus` with an injectable command runner and supervisor directory.
 
@@ -96,19 +82,43 @@ bun run archive connect --kind kingdom --url https://your-kingdom.example --conn
 
 Kingdom takes the owner from the runtime credential; `--owner-model`, `--organization-id` and `--space-id` narrow it to an organization or space that owner manages. A forwarding connection accepts only its bound `projectId`, and the hosted Archive's own token stays in Kingdom's server environment. A Kingdom runtime credential is distinct from a standalone Archive token. Kingdom retains responsibility for memberships, shares, revocation and hosted browsing.
 
-Foundry exposes the same commands through `bun run archive`. Its defaults remain `.foundry/archives/archives.sqlite` and `.foundry/archives.json`. Its durable journal capture automatically publishes matching projects once destination credentials are in the viewer's environment. Restart the viewer after changing destination configuration.
+Foundry writes its captures to the local Archive server through `@inixiative/archive/remote`.
+
+## Routing
+
+Only explicit `projectId` matches authorize publication. An archive with no matching destination stays local. Multiple matches create deliberate separate copies. `routes` previews these destinations before upload. Tags, references and actors never change ownership or routing.
 
-## Routing, tagging and Jev
+## Tags, references, actors and retention
 
-Only explicit `projectId` matches authorize publication. An archive with no matching destination stays local. Multiple matches create deliberate separate copies. `routes` previews these destinations before upload.
+The archive owns its tag system. It keeps two different things apart:
+
+- **Tags** are concepts: the `atlas:<concept>` of repository files a session's tool calls touched (collectors with `--atlas`, from `atlas graph --json`), collector `--tag`s, and tags people add. Heuristic categories are offered as `suggestedTags`, computed on read and never stored.
+- **References** point at items in an integration. Collectors record the session's GitHub repository and branch (`owner/repo`, `owner/repo/tree/branch`); linked GitHub pull requests, issues and commits (`owner/repo#24`, `owner/repo@sha`) and Linear issues (`KEY-12`) are found in the text and counted. A link is a mention, not proof of work. The archive's settings list the integrations it references: GitHub and Linear are recognized natively, and any other integration names the link prefix of its items (for example `https://acme.atlassian.net/browse/`); the item is what follows. Prefixes are literal, so settings cannot make matching slow.
 
 ```sh
-bun run archive tag --id ARCHIVE_ID --tag reviewed
+bun run archive tag --id ARCHIVE_ID --tag reviewed --untag debugging
 ```
 
-Collectors add explicit tags from recorded session metadata: `repo:owner/name` and `branch:name` from git context, and with `--atlas` the `atlas:<concept>` of repository files the session's tool calls touched (from `atlas graph --json` in the session's checkout). Suggestions are computed on read and never stored: heuristic categories, plus `reference` suggestions for linked GitHub pull requests, issues and commits (`github:owner/repo#24`, `github:owner/repo@sha`) and Linear issues (`linear:KEY-12`). A link is a mention, not proof of work, so references stay suggestions.
+Tag edits apply to that archive without a new revision, survive re-capture, and do not sync. Offered tags are defined archive-wide or for one actor. Each session can name its **actor**: a `user`, a `service` such as an API-key run, or a `job` (its id is the job name), with the `integrationId` it ran under when there is one. An organization's archive mostly holds its members' work, filterable per person. Entries the model produced record its `model` and `effort` (from Claude Code assistant records and Codex turn context, per turn); listings summarize them per session as `models` and filter by `model` and `effort`.
+
+The **retention** setting (`retentionDays`, off by default) deletes archives whose latest capture is older than that, at server start and hourly. It deletes only from the archive it is set on; deletions never sync.
+
+### HTTP API
+
+All data endpoints are `POST /api/v1/archive/<action>` with a JSON body and `Authorization: Bearer <token>`:
 
-Tags and suggestions do not change ownership or routing. Jev integration is not enabled: the next step is labeled, shadow-mode tag/destination proposals, scored for accuracy and cross-organization mistakes before any automatic action. Session content must not be sent to Jev without selecting that service for the relevant ownership boundary.
+| Action | Body | Returns |
+|---|---|---|
+| `ingest` | `snapshot`, `previousDigest` | id, digest, revision |
+| `read` | `archiveId`, `revision?` | snapshot and chunks |
+| `list` | filters, `limit?`, `beforeId?` | metadata, `nextCursor` |
+| `search` | filters, `query`, `budget?`, `limit?`, `beforeId?` | matching chunks within the token budget |
+| `tag` | `archiveId`, `add?`, `remove?` | tags |
+| `delete` | `archiveId` | deleted |
+| `settings/read`, `settings/update` | `integrations?`, `retentionDays?` | settings |
+| `tags/list`, `tags/define`, `tags/remove` | `tag`, `actorId?`, `description?` | offered tags with usage counts |
+
+Filters are `projectId`, `source`, `tag`, `actorId`, `model`, `effort` and `reference` (`{integration, ref}`). Jev integration is not enabled. Session content must not be sent to Jev without selecting that service for the relevant ownership boundary.
 
 ## Limits
 
@@ -121,11 +131,15 @@ Tags and suggestions do not change ownership or routing. Jev integration is not
 
 ## Development
 
+Tests create their own databases (`archive_test_*`) in the machine's Archive Postgres, so run `archive up` (or `docker compose up -d postgres`) first, or point `ARCHIVE_TEST_DATABASE_URL` at another pgvector Postgres:
+
 ```sh
-bun test
-bun run typecheck
+archive up
+bun run check
 ```
 
+Schema changes go in `prisma/schema.prisma` with a migration (`bunx prisma migrate dev --name <change>` against a development database).
+
 See [provenance](docs/PROVENANCE.md), [license](LICENSE), and [goals](tickets/README.md). The historical tickets describe earlier scope; this implementation now includes explicit provider collection and authenticated standalone hosting.
 
 ### ChatGPT conversation text

package/compose.yaml

@@ -0,0 +1,37 @@
+# Ports are the archive block of @inixiative/config ports: HTTP 4700, Postgres 6132.
+services:
+  postgres:
+    image: pgvector/pgvector:pg17
+    environment:
+      POSTGRES_USER: archive
+      POSTGRES_PASSWORD: ${ARCHIVE_POSTGRES_PASSWORD:-archive}
+      POSTGRES_DB: archive
+    ports:
+      - "127.0.0.1:${ARCHIVE_POSTGRES_PORT:-6132}:5432"
+    volumes:
+      - ${ARCHIVE_DATA_DIR:-./data}/postgres:/var/lib/postgresql/data
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "pg_isready", "-U", "archive"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+  archive:
+    image: ghcr.io/inixiative/archive:${ARCHIVE_VERSION:-latest}
+    command: ["bun", "run", "src/cli.ts", "serve", "--home", "/data", "--hostname", "0.0.0.0", "--sync"]
+    depends_on:
+      postgres:
+        condition: service_healthy
+    ports:
+      - "127.0.0.1:${ARCHIVE_PORT:-4700}:4700"
+    environment:
+      ARCHIVE_SERVER_TOKEN: ${ARCHIVE_SERVER_TOKEN:?Set a unique random token of at least 32 characters}
+      DATABASE_URL: postgresql://archive:${ARCHIVE_POSTGRES_PASSWORD:-archive}@postgres:5432/archive
+    volumes:
+      - ${ARCHIVE_DATA_DIR:-./data}/config:/data
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "bun", "-e", "fetch('http://127.0.0.1:4700/health').then(r=>{if(!r.ok)process.exit(1)})"]
+      interval: 30s
+      timeout: 5s
+      retries: 3

package/package.json

@@ -1,10 +1,9 @@
 {
   "name": "@inixiative/archive",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
-    "./local": "./src/local.ts",
     "./import": "./src/import.ts",
     "./client": "./src/client.ts",
     "./config": "./src/config.ts",
@@ -15,10 +14,15 @@
     "./collector": "./src/collector.ts",
     "./chatgpt": "./src/chatgpt.ts",
     "./tags": "./src/tags.ts",
-    "./agents": "./src/agents.ts"
+    "./agents": "./src/agents.ts",
+    "./store": "./src/store.ts",
+    "./remote": "./src/remote.ts",
+    "./schemas": "./src/schemas.ts"
   },
   "files": [
-    "src"
+    "src",
+    "prisma",
+    "compose.yaml"
   ],
   "scripts": {
     "test": "bun test tests",
@@ -28,15 +32,17 @@
     "check": "bun run typecheck && bun run lint && bun run test",
     "prepublishOnly": "bun run check",
     "lint": "biome check .",
-    "prepare": "lefthook install"
+    "prepare": "lefthook install && prisma generate"
   },
   "dependencies": {
+    "@prisma/client": "^6.6.0",
     "js-tiktoken": "1.0.21",
+    "prisma": "^6.6.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",
-    "@inixiative/config": "^0.5.39",
+    "@inixiative/config": "^0.5.44",
     "@types/bun": "1.4.2",
     "lefthook": "2.1.9",
     "typescript": "6.0.3"

package/prisma/migrations/20261001022030_init/migration.sql

@@ -0,0 +1,119 @@
+-- CreateExtension
+CREATE EXTENSION IF NOT EXISTS "pg_trgm";
+
+-- CreateExtension
+CREATE EXTENSION IF NOT EXISTS "vector";
+
+-- CreateTable
+CREATE TABLE "settings" (
+    "key" TEXT NOT NULL,
+    "value" JSONB NOT NULL,
+
+    CONSTRAINT "settings_pkey" PRIMARY KEY ("key")
+);
+
+-- CreateTable
+CREATE TABLE "archives" (
+    "id" TEXT NOT NULL,
+    "seq" BIGSERIAL NOT NULL,
+    "digest" TEXT NOT NULL,
+    "revision" INTEGER NOT NULL,
+    "source" TEXT NOT NULL,
+    "projectId" TEXT,
+    "actorId" TEXT,
+    "capturedAt" DOUBLE PRECISION NOT NULL,
+    "summary" JSONB NOT NULL,
+
+    CONSTRAINT "archives_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "revisions" (
+    "archiveId" TEXT NOT NULL,
+    "revision" INTEGER NOT NULL,
+    "digest" TEXT NOT NULL,
+    "snapshot" JSONB NOT NULL,
+
+    CONSTRAINT "revisions_pkey" PRIMARY KEY ("archiveId","revision")
+);
+
+-- CreateTable
+CREATE TABLE "chunks" (
+    "archiveId" TEXT NOT NULL,
+    "revision" INTEGER NOT NULL,
+    "position" INTEGER NOT NULL,
+    "id" TEXT NOT NULL,
+    "entryId" TEXT NOT NULL,
+    "sourceRef" TEXT NOT NULL,
+    "kind" TEXT NOT NULL,
+    "start" INTEGER NOT NULL,
+    "end" INTEGER NOT NULL,
+    "text" TEXT NOT NULL,
+    "tokenCount" INTEGER NOT NULL,
+    "embedding" vector(1536),
+
+    CONSTRAINT "chunks_pkey" PRIMARY KEY ("archiveId","revision","position")
+);
+
+-- CreateTable
+CREATE TABLE "tag_edits" (
+    "archiveId" TEXT NOT NULL,
+    "tag" TEXT NOT NULL,
+    "added" BOOLEAN NOT NULL,
+
+    CONSTRAINT "tag_edits_pkey" PRIMARY KEY ("archiveId","tag")
+);
+
+-- CreateTable
+CREATE TABLE "tag_definitions" (
+    "actorId" TEXT NOT NULL,
+    "tag" TEXT NOT NULL,
+    "description" TEXT,
+
+    CONSTRAINT "tag_definitions_pkey" PRIMARY KEY ("actorId","tag")
+);
+
+-- CreateTable
+CREATE TABLE "receipts" (
+    "archiveId" TEXT NOT NULL,
+    "destination" TEXT NOT NULL,
+    "digest" TEXT NOT NULL,
+
+    CONSTRAINT "receipts_pkey" PRIMARY KEY ("archiveId","destination")
+);
+
+-- CreateTable
+CREATE TABLE "outbox" (
+    "archiveId" TEXT NOT NULL,
+    "destination" TEXT NOT NULL,
+    "revision" INTEGER NOT NULL,
+
+    CONSTRAINT "outbox_pkey" PRIMARY KEY ("archiveId","destination")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "archives_seq_key" ON "archives"("seq");
+
+-- CreateIndex
+CREATE INDEX "archives_projectId_idx" ON "archives"("projectId");
+
+-- CreateIndex
+CREATE INDEX "archives_actorId_idx" ON "archives"("actorId");
+
+-- CreateIndex
+CREATE INDEX "chunks_text_idx" ON "chunks" USING GIN ("text" gin_trgm_ops);
+
+-- AddForeignKey
+ALTER TABLE "revisions" ADD CONSTRAINT "revisions_archiveId_fkey" FOREIGN KEY ("archiveId") REFERENCES "archives"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "chunks" ADD CONSTRAINT "chunks_archiveId_revision_fkey" FOREIGN KEY ("archiveId", "revision") REFERENCES "revisions"("archiveId", "revision") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "tag_edits" ADD CONSTRAINT "tag_edits_archiveId_fkey" FOREIGN KEY ("archiveId") REFERENCES "archives"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "receipts" ADD CONSTRAINT "receipts_archiveId_fkey" FOREIGN KEY ("archiveId") REFERENCES "archives"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "outbox" ADD CONSTRAINT "outbox_archiveId_fkey" FOREIGN KEY ("archiveId") REFERENCES "archives"("id") ON DELETE CASCADE ON UPDATE CASCADE;

package/prisma/migrations/migration_lock.toml

@@ -0,0 +1,3 @@
+# Please do not edit this file manually
+# It should be added in your version-control system (e.g., Git)
+provider = "postgresql"

package/prisma/schema.prisma

@@ -0,0 +1,125 @@
+generator client {
+  provider        = "prisma-client-js"
+  previewFeatures = ["postgresqlExtensions"]
+}
+
+datasource db {
+  provider   = "postgresql"
+  url        = env("DATABASE_URL")
+  extensions = [vector, pg_trgm]
+}
+
+/// Archive-wide values: the source identity, and the settings (integrations, retention).
+model Setting {
+  key   String @id
+  value Json
+
+  @@map("settings")
+}
+
+/// One session. `summary` is its listing (snapshot metadata, tags as captured, models,
+/// references, suggestions), recomputed on capture and when settings change.
+model Archive {
+  id         String @id
+  /// Insertion order: listings are newest first.
+  seq        BigInt @unique @default(autoincrement())
+  digest     String
+  revision   Int
+  source     String
+  projectId  String?
+  actorId    String?
+  capturedAt Float
+  summary    Json
+
+  revisions Revision[]
+  tagEdits  TagEdit[]
+  receipts  Receipt[]
+  outbox    Outbox[]
+
+  @@index([projectId])
+  @@index([actorId])
+  @@map("archives")
+}
+
+/// An immutable revision of a session.
+model Revision {
+  archiveId String
+  revision  Int
+  digest    String
+  snapshot  Json
+
+  archive Archive @relation(fields: [archiveId], references: [id], onDelete: Cascade)
+  chunks  Chunk[]
+
+  @@id([archiveId, revision])
+  @@map("revisions")
+}
+
+/// Lossless text chunks of a revision, in order, for search.
+model Chunk {
+  archiveId  String
+  revision   Int
+  position   Int
+  id         String
+  entryId    String
+  sourceRef  String
+  kind       String
+  start      Int
+  end        Int
+  text       String
+  tokenCount Int
+  /// Reserved for semantic search; nothing writes it yet.
+  embedding  Unsupported("vector(1536)")?
+
+  revisionRef Revision @relation(fields: [archiveId, revision], references: [archiveId, revision], onDelete: Cascade)
+
+  @@id([archiveId, revision, position])
+  @@index([text(ops: raw("gin_trgm_ops"))], type: Gin)
+  @@map("chunks")
+}
+
+/// A tag added (added = true) or removed from what the session was captured with.
+model TagEdit {
+  archiveId String
+  tag       String
+  added     Boolean
+
+  archive Archive @relation(fields: [archiveId], references: [id], onDelete: Cascade)
+
+  @@id([archiveId, tag])
+  @@map("tag_edits")
+}
+
+/// A tag this archive offers: archive-wide (actorId "") or for one actor.
+model TagDefinition {
+  actorId     String
+  tag         String
+  description String?
+
+  @@id([actorId, tag])
+  @@map("tag_definitions")
+}
+
+/// The digest a destination last acknowledged.
+model Receipt {
+  archiveId   String
+  destination String
+  digest      String
+
+  archive Archive @relation(fields: [archiveId], references: [id], onDelete: Cascade)
+
+  @@id([archiveId, destination])
+  @@map("receipts")
+}
+
+/// A revision queued for a destination.
+model Outbox {
+  archiveId   String
+  destination String
+  revision    Int
+
+  archive Archive @relation(fields: [archiveId], references: [id], onDelete: Cascade)
+
+  @@id([archiveId, destination])
+  @@map("outbox")
+}

package/src/agents.ts

@@ -39,8 +39,8 @@ export const collectorAgentSchema = z.strictObject({
 });
 export const agentsConfigSchema = z
   .strictObject({
-    serve: z.strictObject({ port: z.number().int().min(1).max(65535).optional() }).optional(),
-    sync: z.boolean().optional(),
+    /** The Archive server collectors write to; the token is the home's `server.token`. */
+    server: z.strictObject({ url: z.url() }).optional(),
     collectors: z.array(collectorAgentSchema).max(100),
   })
   .refine(
@@ -82,9 +82,10 @@ export interface AgentUnitOptions {
 }
 export const packageCliPath = () => fileURLToPath(new URL('./cli.ts', import.meta.url));
 
-export function collectorArgs(c: CollectorAgent) {
+export function collectorArgs(c: CollectorAgent, server?: { url: string }) {
   return [
     'collect',
+    ...(server ? ['--url', server.url] : []),
     '--directory',
     c.directory,
     '--source',
@@ -113,18 +114,7 @@ export function agentUnits(config: AgentsConfig, options: AgentUnitOptions): Age
       stderr: join(home, 'logs', `${label}.err.log`),
     };
   };
-  return [
-    ...(config.serve
-      ? [
-          unit('local', [
-            'serve',
-            ...(config.serve.port ? ['--port', String(config.serve.port)] : []),
-          ]),
-        ]
-      : []),
-    ...(config.sync ? [unit('sync', ['sync', '--watch'])] : []),
-    ...config.collectors.map((c) => unit(`collect.${c.name}`, collectorArgs(c))),
-  ];
+  return config.collectors.map((c) => unit(`collect.${c.name}`, collectorArgs(c, config.server)));
 }
 
 const xml = (value: string) =>