Personal Context Protocol

PCP is a small Next.js + Postgres app for recording AI sessions with least-privilege tokens. It can run on Vercel + Neon or locally with Docker Compose.

Runtime Shape

  • Next.js 14 App Router, React, TypeScript

  • Next.js API routes

  • Drizzle ORM

  • Neon Postgres

  • Zod request validation

  • Vitest tests

Workflow

  1. Deploy initialization creates the app schema and admin credential.

  2. Human logs in with PCP_ADMIN_TOKEN or the generated first-login UI token.

  3. Human creates topics and sessions one-click (names are generated if omitted).

  4. Human edits, moves, archives, or restores sessions from the dashboard.

  5. Human generates a recording URL + access token pair for one AI agent/session, choosing a token expiration (default 7 days).

  6. The AI fetches the recording URL to discover routes, then records via POST /api/v1/agent/sessions/:sessionId/messages (or /compact, /ingest) with Authorization: Bearer <access-token>.

  7. Human reviews messages, compactions, events, and token status in the admin UI.

Invariants

  • AI tokens are scoped to exactly one session.

  • AI requests cannot include topic fields.

  • Messages are append-only.

  • Tokens are stored as salted hashes.

  • Admin-only routes require the UI token.

Deploy

  1. Deploy the repo to Vercel.

  2. Create a Neon database.

  3. Set DATABASE_URL, PCP_INSTANCE_SECRET, and PCP_APP_URL.

  4. Redeploy. Build-time deploy initialization creates the schema and admin credential. If PCP_ADMIN_TOKEN is not set, PCP generates a temporary first-login token and prints it once in deployment logs. Change it in Settings after login.

See deployment-vercel-neon.md or deployment-docker-compose.md for exact deployment commands.

References