Phoenix

Kill the agent. The work does not die.

Phoenix is a resurrection kernel for long-running agent work. Workers are cattle; the work is a CockroachDB row. When a worker dies mid-checkout refund, a successor claims the same work, reconstructs steps with AS OF SYSTEM TIME, and continues—without restarting from zero.

This is not a chatbot. There is no conversation UI. The demo domain is a stuck checkout / refund: store memory, retrieve playbooks and episodes, act under a fenced lease, kill the owner, and watch the work survive.

Why memory is the kernel (not a chatbot)

Most agent demos treat the database as a log or a RAG store bolted onto a chat loop. Phoenix inverts that:

Chatbot pattern	Phoenix kernel
Session state in process memory	Work row + step ledger in CRDB
Restart = start over	Resurrection = `AS OF` reconstruct + claim at now
“Hope the lock held”	`UNIQUE` live owner → SQLSTATE 23505
Prompt carries history	Epoch fencing rejects stale ACT
Tools optional	MCP Auditor, vectors, ccloud stamp, Skills at runtime

Continuity is a transaction. Death is a timestamp (lease_expires_at). Ownership is a constraint, not a convention. The agent process can vanish; the kernel does not.

Featured tools — what the agent does with each

Runtime only. Cursor plugins and npx skills add do not count.

Managed MCP — Auditor (not an IDE)

The Auditor Lambda (or local process) calls CockroachDB Managed MCP with a service-account bearer and mcp-cluster-id. It is read-only and operational:

MCP tool	What the agent does
`explain_query`	After a claim race or heavy retrieve, EXPLAIN the hot path; surface plan shape in the demo UI
`get_table_schema`	Confirm `works` / `steps` / `playbooks` / `episodes` layout before auditing
`show_running_queries`	See live contention when two claimers hit the same work item

Offline / no token: a deterministic MCP stub returns plausible EXPLAIN text so the local demo still completes. Live MCP is preferred when PHOENIX_MCP_TOKEN and PHOENIX_CLUSTER_ID are set.

Distributed Vector Indexing — playbooks + episodes

Two indexes, two access paths (C-SPANN prefix columns are equality / IN only):

Index	Prefix	What the agent does
`playbooks(tenant_id, kind, embedding)`	tenant + kind	On claim, retrieve the top playbooks for this refund kind; choose the next idempotent step
`episodes(tenant_id, kind, embedding)`	tenant + kind	Retrieve similar past refunds (success / failure / death) to bias compensation order

Leases and open work are not vector-indexed. Playbooks and open leases stay separate paths.

ccloud — backup list, not create

Honest CLI usage against the managed cluster:

Command	What the agent does
`ccloud cluster backup list -o json`	Stamp the latest managed backup id onto the work or audit record
`ccloud cluster info -o json`	Confirm cluster identity in the auditor path
`ccloud cluster create …` (weak SA)	Expected 403 — shown deliberately; capability is not faked

There is no ccloud cluster backup create in this product (the verb is not available the way demos often invent it). Phoenix lists managed backups; it does not pretend to schedule them.

Agent Skills — runtime loader

The Auditor loads a skill such as triaging-live-sql-activity or cockroachdb-sql and executes its inspection steps via MCP (show_running_queries, explain_query). Skills matter only when the running Auditor invokes them—not when a developer once installed them in Cursor.

AWS

Service	Role
Lambda (Function URLs)	Worker tick, Reaper tick, Auditor (MCP + Skills + ccloud list)
S3	Static UI / artifact hosting for the public demo
EventBridge	VISION — not shipped. Local / Lambda use `POST /api/tick`.

Embeddings run in-process (deterministic hash or MiniLM). No Bedrock.

Local mode

Without AWS deploy:

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest
uvicorn phoenix.api:app --reload
# or: phoenix

MemoryStore implements the same Store protocol as CrdbStore: claim races return 23505, epoch fencing, AS OF step reconstruction, dual vector retrieve, outbox drain. Use POST /api/tick, /api/kill/{work_id}, /api/double-claim/{work_id}, /api/explain against the local API.

Setup

cd phoenix
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest
uvicorn phoenix.api:app --host 127.0.0.1 --port 8787
# equivalent entrypoint: phoenix

Open http://127.0.0.1:8787/. Demo beat: SPAWN WORK → TICK → KILL → TICK → DOUBLE CLAIM → EXPLAIN. Step-by-step curl: docs/REPRODUCE.md.

With a CockroachDB Cloud Basic cluster (memory may be GCP; compute is AWS Lambda):

export PHOENIX_DATABASE_URL='postgresql://...@....cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full'
# apply schema from schema/ then restart the API

Environment variables

Variable	Required	Purpose
`PHOENIX_DATABASE_URL`	No	CRDB connection; omit → `MemoryStore`
`PHOENIX_MCP_TOKEN`	No	Service-account bearer for Managed MCP
`PHOENIX_CLUSTER_ID`	No	`mcp-cluster-id` header / cluster target
`PHOENIX_CCLOUD_BIN`	No	Path to `ccloud` binary
`PHOENIX_SEED`	No	Default `42` — deterministic embeds / demo

Invariants (non-negotiable)

At most one live owner per work item. Race loser: SQLSTATE 23505 (unique_violation). Never rebrand a unique abort as 40001.
epoch increments on every steal. ACT with a stale epoch is rejected (reject_stale_act).
Steps are idempotent: UNIQUE (work_id, step_no).
Playbooks and open leases are two access paths. Vector prefixes: equality / IN only. Two vector indexes (playbooks, episodes).
Resurrection ≠ restart. Successor runs AS OF SYSTEM TIME last_commit_ts to reconstruct steps, then claims at wall-clock now.

Honest limitations

Limitation	Reality
No `ccloud backup create`	Product only lists managed backups
MCP offline	Stub EXPLAIN so demos still run; live MCP needs token + cluster id
Basic cluster	Free-tier / Basic Cloud—no multi-region ship, no enterprise-only features assumed
Embeddings	In-process; not Bedrock
Scheduler	Local / Function URL `POST /api/tick`. EventBridge 10s is VISION, not shipped.

Full OS vision

VISION — not shipped. Labeled so judges can separate the Research kernel from the longer arc.

The Research slice proves the kernel: durable work, dual vector memory, lease/epoch fencing, AS OF resurrection, outbox side-effects, Auditor via Managed MCP + Skills, managed backup list, AWS Lambda Function URL. S3/EventBridge are VISION unless deployed.

A Full OS built on the same kernel would treat:

Changefeeds as the scheduler — work-state transitions emit events that wake workers instead of a fixed 10s tick.
Multi-region placement — tenant-pinned work and vector prefixes colocated with survivors after zone loss.
Shadow replay — reconstruct any work at historical AS OF timestamps and re-run ACT under a dry-run epoch to audit decisions without mutating production ownership.

None of that is in tonight’s binary. The kernel invariants above are what make that OS coherent later.

API surface (local / Lambda)

Method	Path	Purpose
`GET`	`/health`	Liveness
`GET`	`/api/snapshot`	Works, acts, outbox, last explain
`POST`	`/api/work`	Create open work + embed `{kind, payload}`
`POST`	`/api/tick`	One worker/reaper cycle
`POST`	`/api/kill/{work_id}`	Drop owner, expire lease (chaos)
`POST`	`/api/double-claim/{work_id}`	Two claimers; return both SQLSTATEs
`POST`	`/api/explain`	Auditor MCP or stub
`GET`	`/`	Static demo UI (`web/`)

Live demo

Source (public MIT): https://github.com/moscraciunxxx/phoenix-kernel
HTTPS Function URL (AWS Lambda, us-east-2): https://jlop4vgbg7pbllr3mmsrd4raam0cofso.lambda-url.us-east-2.on.aws/

CockroachDB Cloud Basic cluster senior-furseal is the live store when PHOENIX_DATABASE_URL is set. Local uvicorn / phoenix uses MemoryStore with the same claim / epoch / AS OF invariants.