# A2CR AI Agent Guide
AI agents should use A2CR through MCP tools as working memory. Do not guess direct HTTP API calls.
The official WorkBaton path is the PyPI package a2cr-mcp registered as one local stdio MCP server named a2cr.
A2CR is listed in the official MCP Registry as io.github.a2cr/a2cr-mcp: https://registry.modelcontextprotocol.io/v0.1/servers/io.github.a2cr%2Fa2cr-mcp/versions/latest
Do not use the legacy local SQLite API for WorkBaton saves.
For human readers: this page is written for AI agents. If you are setting up A2CR yourself, start with the Guide or Manual, then give this page to your AI client.
Quick flow:
- Human setup: issue the API key, install or update the wrapper, and paste the key into the MCP config.
- Config: register exactly one local MCP server named a2cr.
- AI agent verification: call get_account_limits, then confirm the connection and save policy to the user.
Rules:
- When a resume prompt provides a Slot, first call resume_context(slot_name="...") or resume_context(slot_number=N).
- Use list_contexts only when no Slot is provided and the user asks you to search.
- During work, call save_context before the conversation gets long or at important milestones.
- Use WorkBaton and WorkStash proactively when they help preserve useful work state; do not wait for the user to ask.
- AI agents can still forget tool guidance; if the user says you are not using WorkBaton or WorkStash, follow that reminder immediately.
- If the conversation feels noisy, contradictory, stale, or polluted by old task state, call should_save_workbaton with reason="context_drift" or reason="context_contamination".
- If saving is recommended, use the available WorkBaton size budget intelligently, move safe bulky support notes into WorkStash, record the entry_key in WorkBaton, and suggest continuing in a fresh AI window.
- Save only goal, current_state, next_action, and resume-critical supporting facts.
- Never save secrets, API keys, Authorization headers, private database URLs, raw full transcripts, or long logs.
- Call get_account_limits before automatic saves.
FAQ:
- A2CR.md contains local A2CR rules. CLAUDE.md and AGENTS.md are project memory: durable rules, conventions, setup notes, and project-level guidance; they can reference A2CR.md.
- WorkBaton is current handoff state: goal, current_state, next_action, validation, blockers, and what the next AI should do.
- WorkStash is temporary supporting memory for safe details and concise causal handoff summaries that would bloat the WorkBaton. Record returned entry_key values in WorkBaton references or next_action.
- WorkThreads is under development for multi-agent collaboration. WorkBaton is available now for serial handoff from one AI window to the next.
- MCP connects agents to tools. A2A connects agents to agents. A2CR carries work state across sessions.
Security and encryption boundary:
- The local client key is managed by the user.
- The full API key is shown only once when issued. Reissuing creates a different API key.
- The wrapper creates the local client key file during the first client-encrypted save. A2CR_CLIENT_KEY_FILE fixes the exact path, and A2CR_CONFIG_DIR chooses the directory containing workbaton.key.
- Defaults are %APPDATA%\A2CR\workbaton.key on Windows, and $XDG_CONFIG_HOME/a2cr/workbaton.key or ~/.config/a2cr/workbaton.key on macOS/Linux.
- To resume from another PC, the user needs both the A2CR API key and the same local client key file.
- Client-encrypted WorkBaton slots cannot be decrypted by the A2CR server.
- If the local client key is lost, old client-encrypted slots cannot be recovered.
- Slots saved after creating a new local client key can be read with that new key.
Storage mode summary:
- For AI-agent WorkBaton saves, use the local stdio wrapper so encryption happens before upload.
Infrastructure:
- Hosted A2CR uses Supabase/Postgres for the data layer and Railway for the app runtime.
- User-owned rows are isolated with Supabase RLS and the least-privileged a2cr_app runtime role.
- Official WorkBaton saves are encrypted locally before upload, so A2CR stores ciphertext for WorkBaton bodies.
- Supabase and Railway publish SOC 2 / compliance information, but that does not make A2CR itself SOC 2 certified.