@inixiative/archive 0.6.0 → 0.8.0

package/README.md

@@ -4,99 +4,99 @@ 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; with `--sync` it also publishes to its destinations every 30 seconds from the same process. 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 keeps tags captured earlier. 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
 
-Every deployment runs the published image `ghcr.io/inixiative/archive` (tags: version, `latest`, commit SHA), built from main for amd64 and arm64. Give it a persistent volume at `/data`, HTTPS, and a unique `ARCHIVE_SERVER_TOKEN` of at least 32 characters; it needs nothing else and creates its store on first start. Compose (`compose.yaml`, also shipped in the npm package) 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. Pin a version with `ARCHIVE_VERSION`; build from a checkout with `docker compose -f compose.yaml -f compose.build.yaml up -d --build`. The Render blueprint runs the image with a dedicated disk and generated token. Railway deploys the image as a service with a `/data` volume (`railway.json` builds the Dockerfile when deploying from the repository instead).
+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` runs `serve --sync`, so the container publishes to the destinations in its own `/data/destinations.json` (token files must live under `/data` too). It is a separate store from the host agents': 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.
 
 ## Connect through Kingdom
 
-Pair a runtime with Kingdom (Foundry: Settings → Kingdom) and expose its `kingdom_runtime_` credential in an environment variable, then either let Kingdom store the archives:
+Kingdom is the permission hub. Your machine's Archive talks directly only to local pieces, such as your local Foundry. It reaches a hosted Archive through Kingdom, by presenting a Signet.
+
+First, pair this Archive with Kingdom:
 
 ```sh
-bun run archive connect --kind kingdom --url https://your-kingdom.example --project-id inixiative --token-env KINGDOM_ARCHIVE_TOKEN
+bun run archive pair --kingdom https://api.your-kingdom.example --name "Work laptop"
 ```
 
-or forward them through Kingdom to a hosted Archive it has bound for that project:
+`pair` creates a device key in `<home>/kingdom/` and asks Kingdom to pair this Archive, identified by its `sourceId`. It prints a review code and a link. Open the link, choose the owner and the hosted Archives this machine may write to, and approve. The command waits for the approval, then saves the delivered Signet credential (0600) and lists the libraries it may write to.
+
+Next, route a project to one of those libraries:
 
 ```sh
-bun run archive connect --kind kingdom --url https://your-kingdom.example --connection-id inixiative --project-id inixiative --token-env KINGDOM_ARCHIVE_TOKEN
+bun run archive connect --kind kingdom --url https://api.your-kingdom.example --credential-file ~/.archive/kingdom/signet-SIGNET.json --integration-id HOSTED_ARCHIVE_INTEGRATION --resource-id LIBRARY --project-id inixiative
 ```
 
-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.
+`connect` checks that the Signet grants `sessions.write` on that library before it saves anything. `serve --sync` then sends each changed session through `POST /api/v1/access/execute`. Every call carries the Signet's access token and a fresh DPoP proof (`@inixiative/signet` renews the token).
+
+Kingdom enforces the grant on every write:
+
+- It accepts only snapshots whose `sourceId` is this Archive's.
+- It records the paired integration on the session's actor.
+- It resolves a revision conflict from this source by writing over the hosted head. Older captures are still refused.
+
+Each write is usage on the Signet. Revoke the Signet, or pause the local Archive integration in Kingdom, to stop it. `search --remote` uses `documents.search` when the Signet grants it.
 
-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.
+Kingdom keeps no archive store. It forwards each write to the hosted Archive server, whose own token stays in Kingdom as an encrypted credential.
+
+Foundry writes its captures to the local Archive server through `@inixiative/archive/remote`.
 
 ## Routing
 
@@ -145,11 +145,15 @@ Filters are `projectId`, `source`, `tag`, `actorId`, `model`, `effort` and `refe
 
 ## 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

@@ -1,16 +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:-4411}:4411"
+      - "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}:/data
+      - ${ARCHIVE_DATA_DIR:-./data}/config:/data
     restart: unless-stopped
     healthcheck:
-      test: ["CMD", "bun", "-e", "fetch('http://127.0.0.1:4411/health').then(r=>{if(!r.ok)process.exit(1)})"]
+      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.6.0",
+  "version": "0.8.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,14 @@
     "./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",
+    "prisma",
     "compose.yaml"
   ],
   "scripts": {
@@ -29,15 +32,18 @@
     "check": "bun run typecheck && bun run lint && bun run test",
     "prepublishOnly": "bun run check",
     "lint": "biome check .",
-    "prepare": "lefthook install"
+    "prepare": "if git rev-parse --git-dir >/dev/null 2>&1; then lefthook install; fi && prisma generate"
   },
   "dependencies": {
+    "@inixiative/signet": "^0.1.0",
+    "@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.42",
+    "@inixiative/config": "^0.5.53",
     "@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) =>