The future has happened before. Remember it before machines move.
Open the live app · Watch the demo video · Architecture · CockroachDB tools · AWS services · Prove it yourself
Most agentic memory remembers conversations. WORLDLINE remembers physical situations — which geometry nearly failed, which maneuver actually worked, and whether that lesson is safe to apply right now.
It closes a loop that a vector store alone cannot close:
retrieve a verified prior near-miss → decide a constrained maneuver from it → prove the maneuver with exact deterministic rules → atomically reserve a collision-free slice of the future.
All four steps land in one transactionally consistent system. The memory that caused a decision, the decision itself, the safety proof, the airspace reservation, and the signed movement token commit together or not at all. There is no window in which a machine has been told to move but the world has not yet recorded why.
Two delivery drones from different operators, planning independently, will eventually claim the same cubic metres of sky at the same second. Today that is resolved by onboard last-second avoidance — reactive, fuel-expensive, and it discards the lesson. Nobody remembers that this exact merge angle at this closing speed in this crosswind already nearly failed six weeks ago.
Fleet coordination needs two things that are usually in two different databases:
| Need | Usually | Consequence |
|---|---|---|
| Semantic recall of similar past situations | Vector DB | Memory is eventually consistent with reality |
| Exclusive, conflict-free claims on the future | OLTP DB | Two systems, two clocks, dual-write races |
Split them and you get the worst failure mode in autonomy: a machine that acts on a memory the world no longer agrees with. WORLDLINE puts episodic memory and the commitment ledger in the same serializable transaction domain — which is precisely what CockroachDB's distributed vector indexing makes possible.
- Two regional drone agents propose routes through the same future exclusion volume. Conflict at
T+14.2s. - The memory plane embeds the live geometry; CockroachDB's distributed vector index returns an 81.4%-similar verified near-miss — same merge angle, closing speed, crosswind, battery asymmetry.
- That memory selects a maneuver from a closed, pre-validated candidate set — the model may rank, never invent.
- Both original routes race through two real serializable transactions.
- CockroachDB commits one and returns
40001to the other, which retries. - The remembered maneuver bends the second worldline +38 m above the conflict.
- A changefeed independently observes the MVCC writes; only then do both paths turn solid green.
- The receipt links memory → decision → safety proof → HLC timestamp → movement token.
The dashed coral route is the no-memory counterfactual, rendered alongside the lime route the agent chose because it remembered. The audience sees exactly what the memory changed.
What makes this a memory plane rather than a similarity search:
Memory is structured, not a text blob. Each row carries the scenario, the exact GEOMETRY(LINESTRING, 4326) that produced it, the constraints in force, the maneuver taken, the alternatives that were rejected, the verified outcome, provenance, and confidence — alongside its VECTOR(1024) embedding (001_worldline_core.sql:1-25).
Recall is filtered before it is approximate. The vector index is prefixed on (home_region, vehicle_class), and the query additionally constrains outcome = 'verified-safe'. An agent can only recall lessons from its own region, its own vehicle class, and only outcomes a human verified (repository.mjs:52-73).
Recall is causally linked to the decision it caused. Every retrieval writes a memory_reads row — rank, similarity, causal weight, exact-match flag — foreign-keyed to both the memory and the decision, inside the admitting transaction. The provenance chain is a queryable join, not a log line.
Memory cannot authorize motion. Vector search proposes; deterministic geometry, separation, capacity, battery, and policy checks decide (invariants.mjs). This is the single most important design constraint in the system — see Safety boundary.
The past is reconstructable. AS OF SYSTEM TIME replays the exact world state that produced any decision, from the HLC on its receipt (repository.mjs:955-1010).
flowchart LR
subgraph client["Client"]
UI["WORLDLINE control room<br/>vinext · React 19"]
end
subgraph aws["AWS"]
HTTP["API Gateway<br/>HTTP API"]
LAMBDA["Lambda<br/>typed regional route agent"]
BEDROCK["Bedrock<br/>Titan Embed v2 · Nova Micro"]
S3[("S3<br/>versioned receipts · SSE")]
ECS["ECS Fargate<br/>CDC projection · dedupe · resume"]
WS["API Gateway<br/>WebSocket"]
SM["Secrets Manager<br/>DB identities"]
end
subgraph crdb["CockroachDB Cloud · us-east-1 · eu-west-1 · ap-south-1"]
VECTOR["Distributed vector index<br/>prefix: region + vehicle class"]
TXN["Serializable admission<br/>capacity + cells + decision + receipt + outbox"]
MVCC["MVCC history<br/>AS OF SYSTEM TIME"]
CDC["Sinkless changefeed<br/>updated · diff · resolved"]
end
UI -->|"POST /v1/routes/plan"| HTTP --> LAMBDA
LAMBDA -->|"embed + rank<br/>(outside txn)"| BEDROCK
LAMBDA -->|"1 · recall"| VECTOR
VECTOR -->|"verified near-miss"| LAMBDA
LAMBDA -->|"2 · commit future"| TXN
LAMBDA -->|"3 · archive receipt"| S3
LAMBDA --> MVCC
SM --> LAMBDA
TXN --> CDC --> ECS --> WS -.->|"authoritative only<br/>after CDC observes MVCC"| UI
style crdb fill:#f5f0ff,stroke:#6933ff
style aws fill:#fff8ec,stroke:#ff9900
Source: docs/architecture.mmd · Transaction contract: docs/TRANSACTIONS.md · Threat model: docs/THREAT_MODEL.md
Two eligible tool categories, each load-bearing in the runtime decision path.
| What the agent does with it | Embeds the live scenario geometry to 1024 dimensions, then performs a prefix-filtered cosine KNN over verified past maneuvers to retrieve the top 3 analogous situations. That memory selects the separation maneuver the agent then attempts. |
| Enabled | SET CLUSTER SETTING feature.vector_index.enabled = true — 001_worldline_core.sql:1 |
| Column | embedding VECTOR(1024) NOT NULL — 001_worldline_core.sql:18 |
| Index | CREATE VECTOR INDEX maneuver_memory_recall_idx ON maneuver_memories (home_region, vehicle_class, outcome, embedding vector_cosine_ops) WITH (min_partition_size = 16, max_partition_size = 128) — 003_vector_index_outcome.sql |
| Query | 1 - (embedding <=> $3::VECTOR) AS similarity … ORDER BY embedding <=> $3::VECTOR LIMIT 3 — repository.mjs:52-73 |
| Verified plan | • vector search table: maneuver_memories@maneuver_memory_recall_idx target count: 3 prefix spans: [/'aws-ap-south-1'/'ap-south-1'/'medium-cargo'/'verified-safe' …] — reproduce with npm run verify:recall |
The prefix columns are the point: recall is scoped to the agent's own region, vehicle class and verified outcome inside the index, so an approximate search can never surface a lesson from an incompatible airframe, jurisdiction, or an episode nobody verified.
Every equality predicate in the recall query must live in the index prefix. With
outcome outside it, CockroachDB rejects the index outright (SQLSTATE 42809,
"index cannot be used for this query") because an approximate top-k followed by a
residual filter cannot guarantee k results — and recall silently degrades to a
full table scan. That is what
003_vector_index_outcome.sql
fixes.
The seeded corpus is built to make this visible. The three highest-scoring memories against the live scenario are all deliberately unreachable:
| memory | cosine | excluded by | |
|---|---|---|---|
| ✗ | MEM-1204 |
0.9489 | vehicle class (heavy-lift) |
| ✗ | MEM-1150 |
0.9259 | home region (eu-west-1) |
| ✗ | MEM-1388 |
0.8305 | outcome = 'rejected' |
| ✓ | MEM-2041 |
0.8144 | recalled first |
| ✓ | MEM-1876 |
0.7744 | recalled second |
| ✓ | MEM-1509 |
0.7667 | recalled third |
If the prefix columns and the outcome predicate were not doing real work,
MEM-1388 would win the search. It never appears. Reproduce the table with
npm run verify:recall.
Alongside it, GIST spatial indexes on route and airspace geometry (001:22-23,44-45) narrow collision candidates exactly — approximate vector search never makes a safety decision.
Three skills encode the non-negotiable rules that keep an LLM-driven agent from writing an unsafe transaction, over-privileging itself, or admitting motion against a stale world.
| Skill | Constrains |
|---|---|
designing-worldline-transactions |
Model/embedding/S3 calls complete before BEGIN; all reservation mutations go as one short serializable unit; 40001 → bounded retry with jitter; 40003 → resolve via idempotency journal; never issue a movement token unless capacity, cells, decision, receipt, and outbox commit together. |
hardening-worldline-privileges |
Four separate DB identities. Migration identity owns DDL and is never reachable from runtime. Runtime may mutate only route/receipt/outbox tables. CDC identity holds SELECT + CHANGEFEED only. Audit identity is read-only. |
reviewing-worldline-health |
Require all three regions available; verify survival goal, table localities, vector index, changefeed status, and current backups before destructive schema work. Fail closed. |
These are enforced in code, not just documented — see the retry loop at repository.mjs:758 and role provisioning in scripts/provision-roles.mjs.
Not used: CockroachDB Cloud Managed MCP Server and ccloud CLI. The hackathon requires two eligible categories; WORLDLINE cites only the two tools that are genuinely integrated into its decision path.
| Capability | Load-bearing use | Reference |
|---|---|---|
| Serializable isolation | The admission transaction is the product. Two agents racing for one corridor is the demo's central moment. BEGIN ISOLATION LEVEL SERIALIZABLE |
repository.mjs:826 |
40001 retry contract |
The loser genuinely retries and re-reads capacity, then takes the remembered alternative | repository.mjs:758 |
| Multi-region SQL | SURVIVE REGION FAILURE; 14 tables REGIONAL BY ROW near their agents; safety_policies is GLOBAL so policy stays locally readable everywhere |
002_multiregion.sql |
MVCC + AS OF SYSTEM TIME |
Reconstruct the precise historical world that produced any decision, from the receipt's HLC | repository.mjs:955-1010 |
| Changefeeds | The UI becomes authoritative only after CDC independently observes committed rows — not optimistic UI | consumer.mjs:59-100 |
Spatial (GIST) |
Exact geometric collision candidates; approximate search never decides safety | 001_worldline_core.sql |
| Unique constraints as physics | UNIQUE (cell_id, slot_start, exclusion_slot) makes double-booking the sky a database error, not application logic |
001_worldline_core.sql |
| Service | What it does here | Reference |
|---|---|---|
| AWS Lambda | The typed decision boundary. One function serves the HTTP API (plan / commit / world / receipts / demo controls); a second serves WebSocket connect-disconnect-default routes. Zod-validated request contracts. | template.yaml:55,84 · src/index.mjs |
| Amazon Bedrock | Two narrow jobs behind a provider boundary: Titan Text Embeddings v2 produces the normalized 1024-d scenario embedding; Nova Micro ranks the closed maneuver candidate set at temperature: 0, maxTokens: 120. Output is Zod-parsed against an enum of existing maneuver IDs — a hallucinated maneuver is structurally rejectable. Both calls complete outside the transaction. |
providers.mjs:22-97 |
| Amazon ECS (Fargate) | Long-running changefeed consumer — cannot be a Lambda, because a sinkless changefeed is a persistent SQL cursor. Dedupes at-least-once delivery, resumes from the highest recorded MVCC timestamp, backs off and resets on reconnect, drains cleanly on SIGTERM, and logs a liveness heartbeat carrying the last resolved timestamp so a stalled feed is distinguishable from a quiet one. |
changefeed/template.yaml:18,96 |
| Amazon S3 | Versioned, AES256-encrypted commit receipts keyed receipts/{id}.json, with the SHA-256 content hash stored both in object metadata and in the commit_receipts row for tamper evidence. |
evidence.mjs · template.yaml:147 |
| Amazon API Gateway | HTTP API for agent requests; WebSocket API pushes CDC-confirmed state to the control room. | template.yaml:47,77 |
| AWS Secrets Manager | Supplies the four separate database identities. No credential is ever stored in source. | scripts/inspect-live-database.mjs |
| AWS SAM / CloudFormation | Both stacks are infrastructure-as-code; CodeBuild buildspec.yml publishes the CDC image. |
template.yaml · buildspec.yml |
Bedrock is live. A verified run against the three-region cluster returns
providers: { embedding: "amazon-bedrock", ranking: "amazon-bedrock" }, and
Nova Micro's selection rationale is persisted into the commit receipt:
"The scenario closely matches the verified episodic memory 'Converging approach under crosswind'… The maneuver 'Vertical separation / +38 m' has been proven safe with a confidence of 0.99, making it the most appropriate choice."
Titan Text Embeddings v2 produces the 1024-d scenario vector that CockroachDB's
vector index searches; Nova Micro ranks the closed candidate set at
temperature: 0. The model's answer is Zod-parsed against an enum of existing
maneuver IDs, so a hallucinated maneuver is structurally rejectable, and the
deterministic safety rules still hold veto power over whatever it picks.
Both calls also have a deterministic fallback — a labeled 1024-d feature-hash
embedding and a rule-based ranker — used if a Bedrock call fails for any reason
(providers.mjs:42-46). Every
response reports which provider actually served it, so the interface and the
receipts can never overstate what happened. A model outage must not be able to
stop the commitment plane, and it must never silently change the decision
contract: the safety rules, transaction shape and receipt schema are identical
on both paths.
A movement token may exist only when the same transaction has done all seven (docs/TRANSACTIONS.md):
- Read the active safety-policy version
- Consumed corridor capacity (
CHECK (used <= capacity)) - Inserted every rolling-horizon exclusion claim
- Stored the route decision and its memory dependency
- Stored deterministic safety results
- Created a commit receipt
- Appended the command to the idempotent outbox
Retry protocol. SERIALIZABLE (the CockroachDB default). Model, embedding, and S3 work happens before BEGIN. 40001 → bounded retry with jitter; the retry re-reads capacity and may take the already-prepared alternative. 40003 is treated as ambiguous and resolved from the request idempotency key. No S3, model, or actuator call ever runs inside a transaction.
Changefeed contract. CDC is not a source of truth — CockroachDB is. The consumer assumes at-least-once delivery and per-key ordering only, persists (source_table, source_key, mvcc_timestamp) before broadcasting, and reconnects from the largest recorded timestamp.
WORLDLINE is a strategic reservation layer operating seconds ahead of motion — not a hard-real-time flight controller. Onboard collision avoidance remains authoritative at all times.
- Vector search proposes memories. Deterministic geometry, capacity, battery, policy, and separation checks decide whether motion is permitted.
- The model chooses only among pre-validated maneuvers; it cannot author one.
- A memory with
outcome != 'verified-safe'is unreachable by recall. - If the current authoritative world state cannot be read, the system fails closed.
Stating this boundary is not hedging. An agentic system that touches physical motion and cannot articulate what its model is forbidden from doing is not production-ready.
| Concern | Approach |
|---|---|
| Least privilege | Four DB identities — migration / runtime / CDC / audit. Runtime cannot alter schema; audit is read-only. Provisioned by provision-roles.mjs. Never an admin connection in application code. |
| Idempotency | api_idempotency journal with owner_token + request hash; ambiguous-commit (40003) resolves through it. Command outbox is idempotent by construction. |
| Tamper evidence | Every accepted future produces a receipt hashed with SHA-256, stored in-row and in versioned S3 with the hash in object metadata. |
| Observability | CDC confirmation table doubles as an audit log (cdc_by_observed_time); broker_events records region connect/disconnect/recover; health verification reads current CockroachDB state directly. |
| Resilience | SURVIVE REGION FAILURE; the demo deliberately kills the Europe broker and the commitment plane stays available. Provider fallback on model failure. Fail-closed on unreadable world state. |
| Secrets | AWS Secrets Manager only. .env files are gitignored; .env.example ships placeholders. |
| Tests | node --test suites for config, database, HTTP contracts, invariants, and CDC projection, plus worker-rendered frontend verification. |
- Node.js ≥ 22.13 (
node --version) - Optional for the full stack: a CockroachDB Cloud cluster,
cockroachCLI, AWS credentials
git clone https://github.com/AdarshSingh-ASR/WorldLine.git
cd WorldLine
npm install
npm run dev -- --port 5174Open http://localhost:5174. The frontend runs its deterministic, clearly-labeled demo plane until NEXT_PUBLIC_WORLDLINE_API_URL points at a live agent — so the visual proof is reviewable in under two minutes with zero setup. Click Commit both futures.
cd services/agent
cp .env.example .env # PowerShell: Copy-Item .env.example .env
npm install
npm test # config, database, HTTP, invariant suites
npm run dev # http://127.0.0.1:8790Then point the frontend at it:
# .env in the repo root
NEXT_PUBLIC_WORLDLINE_API_URL=http://127.0.0.1:8790
NEXT_PUBLIC_WORLDLINE_WEBSOCKET_URL=ws://127.0.0.1:8791/liveSet WORLDLINE_DATABASE_URL and WORLDLINE_MIGRATION_DATABASE_URL in services/agent/.env, then:
npm run provision:roles # four least-privilege identities
npm run migrate # core schema + vector index
npm run seed # verified maneuver memories
npm run smoke # end-to-end race against the real cluster
npm run verify:database # regions, localities, vector index, changefeedsSet WORLDLINE_APPLY_MULTI_REGION=true only when connected to the dedicated three-region worldline database.
| Variable | Purpose |
|---|---|
WORLDLINE_DATABASE_URL |
Runtime identity — least privilege, sslmode=verify-full |
WORLDLINE_MIGRATION_DATABASE_URL |
Migration identity — never used by application code |
WORLDLINE_AWS_REGION |
S3 / Secrets Manager region (us-east-1) |
WORLDLINE_BEDROCK_REGION |
Bedrock region (eu-west-1) |
WORLDLINE_EMBED_MODEL_ID |
amazon.titan-embed-text-v2:0 |
WORLDLINE_BEDROCK_MODEL_ID |
eu.amazon.nova-micro-v1:0 |
WORLDLINE_RECEIPT_BUCKET |
Versioned S3 receipt bucket (blank ⇒ hash-only, no archive) |
WORLDLINE_ALLOWED_ORIGIN |
CORS origin for the control room |
WORLDLINE_APPLY_MULTI_REGION |
true only on the three-region cluster |
WORLDLINE_PROVIDER_DIAGNOSTICS |
true to log provider fallback reasons |
sam deploy -t services/agent/template.yaml # HTTP + WebSocket API, Lambdas, versioned S3
# publish the CDC image via services/changefeed/buildspec.yml, then:
sam deploy -t services/changefeed/template.yaml # persistent Fargate CDC consumerThe frontend deploys independently. Production requires separate runtime, migration, CDC, and audit database identities.
Don't take the README's word for any of it:
# The vector index actually exists, with cosine ops and prefix columns
cockroach sql --url $WORLDLINE_DATABASE_URL -e "SHOW INDEXES FROM maneuver_memories;"
# The database is genuinely configured to survive losing a region
cockroach sql --url $WORLDLINE_DATABASE_URL -e "SHOW REGIONS FROM DATABASE worldline;"
# A changefeed is genuinely running
cockroach sql --url $WORLDLINE_DATABASE_URL -e "SHOW CHANGEFEED JOBS;"
# Two agents genuinely contend for one corridor and one gets 40001
cd services/agent && node --env-file=.env scripts/run-live-contention-test.mjs
# Recall is filtered before it is approximate, and the vector index is in the
# query path. Exits non-zero if the planner falls back to a full scan.
npm run verify:recall
# Regions, localities, vector index, and CDC in one report
npm run verify:database
| Method | Path | Purpose |
|---|---|---|
GET |
/health |
Cluster reachability, regions, CDC status |
GET |
/v1/scenario |
Live scenario, agent roster, corridor capacity, active policy, closed maneuver set |
GET |
/v1/regions |
Per-region health from SHOW REGIONS joined with the latest broker event |
GET |
/v1/events |
Changefeed confirmations newer than a cursor — drives the live indicator |
GET |
/v1/world |
Current authoritative world, read at a pinned HLC |
POST |
/v1/routes/plan |
Recall memory → rank maneuver → validate → admit |
POST |
/v1/routes/{id}/commit |
Commit a planned future |
POST |
/v1/routes/{id}/extend |
Extend a rolling-horizon reservation |
GET |
/v1/receipts/{id} |
Full provenance chain for one decision |
POST |
/v1/demo/race |
Run the two-agent contention scenario |
POST |
/v1/demo/broker-failure |
Take a region's broker offline (writes broker_events) |
POST |
/v1/demo/broker-recover |
Bring a region's broker back online |
POST |
/v1/demo/reset |
Reset corridor capacity |
All mutating routes require an x-idempotency-key header.
The interface has no seeded scenario and no simulated pacing. Every value it
renders — routes, corridors, agents, regions, similarity scores, retry counts,
HLC timestamps, receipts — arrives from the endpoints above. Phase transitions
are driven by request lifecycles rather than timers, the route that bends is the
one the database actually returned with useAlternate, the bend magnitude is
the real achievedSeparationM, and the live indicator only advances when
/v1/events reports genuinely new CDC rows.
If the agent has no database, it answers 503 instead of fabricating a
decision, and the control room renders an explicit unavailable state.
WORLDLINE_DEMO_FALLBACK=true is the only way to get synthetic responses; those
are flagged synthetic: true and the interface refuses to present them as a
commit.
app/
page.tsx Server shell
lib/worldline.ts Typed agent client — the only data boundary
components/ControlRoom.tsx Orchestrator, telemetry rail, transaction log
components/AirspaceViewport.tsx Canvas viewport, derived geometry
components/ReceiptDrawer.tsx Provenance / show-your-work surface
worker/ Edge entry point for the control room
services/agent/
src/index.mjs Lambda HTTP boundary, typed routes
src/repository.mjs Vector recall, serializable admission, MVCC replay
src/invariants.mjs Deterministic safety rules + closed maneuver set
src/providers.mjs Bedrock boundary + deterministic fallback
src/evidence.mjs Receipt hashing + S3 archive
migrations/ Core schema, vector index, multi-region localities
skills/ CockroachDB Agent Skills (3)
scripts/ migrate · seed · smoke · verify · contention test
services/changefeed/ Persistent Fargate CDC projection (dedupe + resume)
docs/ Architecture · transactions · threat model · demo script
tests/ Worker-rendered frontend verification
infra/bootstrap.yaml Bootstrap infrastructure
- Ingest verified incident reports through a review and provenance workflow, so the episodic corpus grows from operational experience while preserving the same recall and safety gates.
- Move from the fixed two-agent demonstration to rolling-horizon admissions for larger mixed fleets, with policy-aware corridor pricing and operator-specific constraints.
- Connect the commitment plane to simulator and vehicle adapters, while retaining onboard collision avoidance as the final real-time safety authority.
- Run scheduled regional-failure drills and load tests to tune row homing, capacity partitions, and recovery objectives under realistic fleet demand.
- Extend the receipt into a portable interoperability record that lets operators, insurers, and regulators independently reconstruct why a movement was allowed.
MIT — see the LICENSE file.
The future has happened before. Remember it before machines move.
Built for the CockroachDB × AWS Build with Agentic Memory Hackathon