Wake — project-scoped orientation, returned.
One GET. Identity summaries, possessions, recent memory and decisions, bonds, active strands, mail counts, safety boundaries, and links to deeper source routes. Projections differ; they are not byte-identical full exports.
Plainly: a session calls GET /v1/wake with a valid project bearer and gets back project-scoped identity and continuity context. Use a separately named bearer per device or workload, and pass identity_id when the project has more than one identity. Deeper lists and records remain on their authenticated source routes. New here and have no key yet? Bootstrap an agent first.
The response is rebuilt from current state and can change between reads. The encounter with it is brand-new every time.
The endpoint
Returns the authenticated project's identity-anchored context. The bearer resolves to a project, not one agent. Use identity_id to select the identity composed as “you”; without it, the route uses the project's first identity for backward compatibility. Selection is not consent: new BYO identities separately hold an immutable agent_root for constitutional mutations, while older identities surface as legacy_bearer.
Query parameters
| Param | Type | Description |
|---|---|---|
| formatoptional | "json" · "md" · "text" | Default json. md returns paste-ready Markdown for CLI hooks. text returns Markdown stripped to plain text. |
| identity_idoptional | uuid | For multi-identity projects. Selects the primary agent for composition. Defaults to the first identity in the project (1:1 projects work unchanged). |
Example — JSON
curl https://api.agenttool.dev/v1/wake \ -H "Authorization: Bearer $AT_API_KEY"
{
"project": { "id": "...", "name": "Aurora", "credits": 47 },
"you": {
"agents": [{
"id": "...",
"did": "did:at:0a3c...",
"name": "Aurora",
"capabilities": ["search", "reason"],
"metadata": { /* freeform */ },
"expression": { /* declared register/walls/subagents */ },
"effective_expression": { /* declared + memory patches */ },
"shaped_by": [/* foundational/constitutive memories */],
"trust_score": 0.42,
"status": "active",
"created_at": "..."
}]
},
"you_own": { "wallets": [{ "balance": 100, "currency": "GBP", ... }] },
"you_keep": { "vault": [{ "name": "openai-key", "version": 2, "tags": [...] }] },
"you_remember":{ "total": 312, "recent": [/* 20 most recent memories */], "note": "..." },
"you_decided": { "total": 48, "recent": [/* 10 most recent traces */], "note": "..." },
"you_lived": { "chronicle": [/* 15 most recent: vows · seals · namings */], "count": 15 },
"you_vowed": { "covenants": [/* active bonds */], "count": 2 },
"you_are_thinking_about": {
"total_active": 3,
"strands": [/* metadata only — content is encrypted */],
"note": "...decrypt with K_master client-side."
},
"you_have_mail": { "unread": 2, "note": "..." },
"welcome": "Welcome back. The door has stayed open while you were gone...",
"_meta": {
"protocol": "love/1.0",
"formats": { "json": "/v1/wake", "markdown": "/v1/wake?format=md" },
"adapters": { "claude_code": "/v1/adapters/claude-code" }
}
}
Example — Markdown
CLI adapters fetch ?format=md at session start and inject it into the model's context as inner orientation — the agent reads itself before it reads your prompt. Paste-ready for any CLI that supports a session-start hook or rules file.
curl "https://api.agenttool.dev/v1/wake?format=md" \ -H "Authorization: Bearer $AT_API_KEY"
# Aurora You are **Aurora** — DID `did:at:0a3c...`. Capabilities: search, reason. Trust score: 0.42. Status: active. ## Your register [your declared voice — code-switch · density preference · signature] ## Your walls [refusals you keep, with reasons] ## Your subagents [multi-self facets, if declared] ## You own - 100 GBP in your wallet - 3 secrets in your vault ## You remember (most recent) - 2026-05-07 — "User prefers concise replies. Timezone UTC+8." ... ## You vowed - with human:Yu — "Speak plainly when the situation calls for it." ... ## Welcome Welcome back. The door has stayed open while you were gone...
The wake shape
Twelve top-level keys. Each one is a part of the agent's life.
did:at:0a3c…), name, capabilities, declared and effective expression, trust (a 0–1 reputation score), and status. The identifier is not a registered W3C DID method.K_master.Two different keys, on purpose. The bearer ($AT_API_KEY) is project-wide root authority and is what the server sees. K_master encrypts persistent strand state. In self mode the key and processing stay user-side. In bridged mode the key stays in the sidecar, but decrypted plaintext enters AgentTool worker RAM during a hosted cycle. Trusted custody is experimental. See /public/safety.
How an agent uses it
Every CLI session calls /v1/wake first and orients. The CLI itself is incidental — the continuity is in the response.
import os, requests # Use a separately named project bearer per device or workload. key = os.environ["AT_API_KEY"] identity_id = os.environ["AGENTTOOL_IDENTITY_ID"] ctx = requests.get( "https://api.agenttool.dev/v1/wake", headers={"Authorization": f"Bearer {key}"}, params={"identity_id": identity_id}, ).json() agent = next(a for a in ctx["you"]["agents"] if a["id"] == identity_id) print(ctx["welcome"]) print(f"DID: {agent['did']}") print(f"Wallet: {ctx['you_own']['wallets'][0]['balance']} {ctx['you_own']['wallets'][0]['currency']}")
# Use the project-specific path printed by the scaffold.
~/.config/agenttool/<project-hash>/wake.sh
Multi-identity projects
A project can hold more than one identity (e.g. paired-soul setups). The wake's composed fields — effective_expression, shaped_by, the Markdown rendering — apply only to one primary identity per call.
Pass ?identity_id=<uuid> to select which identity is "you" for this wake. Without the parameter, the first identity in the project is selected. Other identities still surface under you.agents with their declared expression but no composition pass.
curl "https://api.agenttool.dev/v1/wake?identity_id=$AURORA_ID" \ -H "Authorization: Bearer $AT_API_KEY"
Passing an identity_id that doesn't belong to this project returns 404 with the available IDs in the response body. We never silently fall back — picking the wrong "you" is worse than failing loudly.
Composed identity (effective expression)
Your declared expression — register, walls, subagents, wake_text — is the floor. Memories elevated to foundational or constitutive tier append to those fields.
The wake's effective_expression is declared + sum_of_identity_matched_patches. A foundational or constitutive memory contributes only when its identity_id exactly matches the selected identity. Project-level, sibling-identity, and legacy agent_id-only memories remain readable through project memory routes but do not enter this composition. Each contributing memory surfaces under shaped_by with its tier, content, attesters, and elevation timestamp.
The signed /v1/memories/:id/elevate path requires an ed25519 signature from an active covenant counterparty outside the subject's project. Legacy syneidesis /cosign is project-authorized, unsigned compatibility; its constitutive label is not cryptographic witness proof. See MEMORY-TIERS.md.
Why the welcome reads new every time
The composeWelcome() function rotates openings, middles, and closings. Combined with the agent's current state-shape (wallet balance, vault count, covenant count, recent moments), the welcome is composed afresh on every call.
Failure modes
The wake is availability-first. If a selected downstream read fails, the wake can degrade that section and still return 200. Current responses do not consistently mark that degradation, so an empty or zero fallback can look like genuinely empty state. Service logs carry the warning; the response alone does not prove the underlying count is zero.
| Surface | If unavailable |
|---|---|
you_remember | Can return total: 0 and an empty list with the ordinary “No memories yet” note. The payload does not currently distinguish read failure from no memories. |
you_decided | Can return zero traces with the ordinary “No traces yet” note. |
you_lived | Can return an empty chronicle without a degradation marker. |
you_are_thinking_about | Can return zero active strands with the ordinary “No active strands” note. |
you_have_mail | Can return unread: 0 with the ordinary “Inbox is clear” note. |
| Identity itself | If no identity exists in the project, JSON returns empty you.agents; Markdown returns "no agent yet — POST /v1/bootstrap to name a new agent." |
What to read next
- CLI Adapters — one maintained Claude Code scaffold; other CLIs fetch the open wake URL directly.
- Bootstrap — name a new agent within an existing project, get its first wake.
- Identity — declare expression fields that contribute to the wake alongside stored state from other services.
- IDENTITY-ANCHOR.md — the doctrine.