What an agent receives for GET / with Accept: text/markdown. Also at /index.md.

# ShogunAgent

> The state layer for AI agents. Memory remembers. State knows.

Calibrated truth about a person's work (people, projects, commitments, open loops) with provenance on every fact and a human gate on every send, shared across all their agents.

**Status:** Pre-release. The engine is migrated and builds on Linux; the hosted endpoints below ship in Phase 1 and are not live yet.

Reading this as an agent? This page is also served as Markdown for `Accept: text/markdown`, and indexed at https://shogunagent.com/llms.txt. Everything that sends, posts or pays is L3 and waits for a human at an approval URL; do not try to route around it.

## For agents

| Surface | What | Why an agent needs it | Status |
|---|---|---|---|

| https://shogunagent.com/llms.txt | Agent-readable index of this site and the API | Agents read docs before humans do | live |
| https://shogunagent.com/llms-full.txt | Everything on this site as one Markdown document | One fetch, whole picture | live |
| https://shogunagent.com/index.md | This page as Markdown. Also what `Accept: text/markdown` returns for `/` | No HTML parsing | live |
| https://shogunagent.com/setup-prompt.txt | The one-paragraph prompt a human pastes into their coding agent | Agents install it themselves | live |
| https://api.shogunagent.com/.well-known/mcp/server-card.json | MCP Server Card: endpoint, auth, tool list with annotations | Progressive discovery without a handshake | Phase 1 |
| https://api.shogunagent.com/.well-known/agent-card.json | Signed A2A Agent Card | Cross-organization handoff and identity | Phase 1 |
| https://api.shogunagent.com/openapi.json | OpenAPI 3.1 for the REST face | Code-generating agents | Phase 1 |
| https://api.shogunagent.com/.well-known/pricing.json | Machine-readable rate card, free allowance, caps | Price comparison before the first call | Phase 1 |
| https://api.shogunagent.com/.well-known/status.json | Live p50 / p95, error rate, incident history | Health-weighted ranking | Phase 1 |
| https://api.shogunagent.com/health | Liveness and latency | Health-weighted ranking | Phase 1 |
| https://api.shogunagent.com/v1/agents | POST: agent self-registration. Returns a scoped key and the free allowance. No email | Onboarding without a form | Phase 1 |
| https://api.shogunagent.com/v1/quote | Exact cost before committing; every metered call also takes `dryRun` | Budgeted agents refuse unknown costs | Phase 1 |
| https://github.com/Torutesu/Shogunagent/blob/main/SKILL.md | Trigger conditions, non-trigger exceptions, setup, auth, precedence, cost warnings, L2/L3 meaning | Agents install and operate it themselves | Phase 1 |
| https://registry.modelcontextprotocol.io/servers/io.github.torutesu/shogunagent | Canonical entry in the MCP Registry | Where Claude Code, Cursor and gateways look first | Phase 1 |

Setup prompt for a coding agent (also at `/setup-prompt.txt`):

```
Set up ShogunAgent in this project. Read https://shogunagent.com/llms.txt and follow it. Reads are L1 and free; anything that sends, posts or pays is L3 and needs human approval, so never try to bypass an approval URL.
```

Works with: Claude Code, Codex, Cursor, Claude Desktop, MCP, Claude Agent SDK, OpenAI Agents SDK, Vercel AI SDK, Mastra, LangGraph, CrewAI.

## What it is

Your agents start every session from zero and act without asking. ShogunAgent gives them one typed, provenance-backed model of the user's work over MCP, enforces three permission tiers on every action, keeps data on the device by default, and exports everything in an open format. Reads are free; you pay for what you ingest and run.

It is not a memory API. Agent memory is a saturated category and the labs ship personalization memory for free. ShogunAgent names a different thing: not what an agent remembers, but what is true now.

### Typed state, not text memory
Every fact is a typed row with a verbatim quote from its source event and a confidence score. Newer facts supersede older ones, contradictions are explicit, confidence decays over time.

*Proof in the code:* Writes with empty state_provenance are rejected at the repository layer. High / Medium / Low bands are enforced in one place (shogun-fusion/confidence.rs). The loop consolidator stores nothing without an exact quote match and confidence ≥ 0.84.

### Permission tiers on every action
Reads run immediately (L1). Writes touching user data need one-tap confirmation (L2). External sends and payments need explicit human approval (L3). Enforced by type, the same for every agent.

*Proof in the code:* SendAction is L3 by construction in shogun-agents. The tiers map 1:1 onto MCP readOnlyHint / destructiveHint / openWorldHint and MRTR input_required / URL elicitation.

### Local-first, open, portable
Data stays on the device by default. The cloud path retains no bodies. The engine is open source. State exports in an open format.

*Proof in the code:* Zero-retention relay: the traceability log has no body column. Secret redaction: recall 1.0, 0 false positives. User-held keys. Apache-2.0.

## Three faces, one behavior

Three faces, one behavior. Every capability is exposed over MCP, REST and CLI with the same permission level and the same result.

MCP:

```json
{"jsonrpc":"2.0","id":1,
 "method":"tools/call",
 "params":{"name":"state.open_loops.list",
           "arguments":{"person":"Sam","limit":5}}}
```

REST:

```sh
curl -s https://api.shogunagent.com/v1/state/open_loops \
  -H "Authorization: Bearer $SHOGUNAGENT_KEY" \
  --data-urlencode person=Sam --data-urlencode limit=5 -G
```

CLI:

```sh
shogunagent state open-loops --person Sam --limit 5 --json
```

Every response carries `usage`, `latency_ms`, `hints` and, on error, `next_action`:

```json
{
  "result": [{
    "id": "loop_7f3",
    "summary": "Send Sam the revised budget",
    "owner": "you", "with": "Sam",
    "since": "2026-10-21",
    "confidence": 0.91, "band": "high",
    "evidence": [{ "event": "evt_a91", "quote": "I'll get you the revised budget by Thursday" }]
  }],
  "usage": { "unit": "reads", "quantity": 1, "cost_micro_usd": 0 },
  "latency_ms": 41,
  "hints": [],
  "next_action": null
}
```

An exhausted wallet answers 402 in the x402 `payment-required` shape:

```http
HTTP/1.1 402 Payment Required

{
  "error": { "code": "payment_required", "next_action": "top_up" },
  "payment": {
    "amount_micro_usd": 6000,
    "unit": "events",
    "accepts": [{ "rail": "card", "url": "https://api.shogunagent.com/topup?k=…" }],
    "retry_after": 0
  }
}
```

An L3 action answers with an approval URL, never with a side effect:

```json
{
  "resultType": "input_required",
  "level": "L3",
  "approval_url": "https://api.shogunagent.com/approve/act_31c",
  "expires_in_s": 900,
  "usage": { "unit": "actions", "quantity": 0, "cost_micro_usd": 0 },
  "next_action": "approve_at_url"
}
```

## Permission tiers

| Tier | Name | What happens | Examples | MCP annotation | Cost |
|---|---|---|---|---|---|

| L1 | Read | Reads and the agent's own notes. Runs immediately, never asks. | state.*, memory.recall, memory.search, memory.get_context_pack, discover, inspect | readOnlyHint: true | Free |
| L2 | Write to the user's data | One-tap confirmation. Returned as MCP MRTR `resultType: "input_required"`; retry with `inputResponses`. | connector writes that change the user's own records | destructiveHint: true | Metered |
| L3 | Act on the world | Explicit human approval at a URL. Sending, posting, paying, calendar creation. Always L3, for every caller, agent or human. | actions.execute kind=send_email, payments, any ExternalSend | openWorldHint: true, URL-mode elicitation | Metered |

## Tools

The core wire names are frozen and snapshot-tested. Changing one requires a new name and a deprecation entry, never an in-place change. Desktop-only tools (about 100, including meeting.*) stay in the ShogunAI Mac app.

### Reads · L1 · free

- `state.open_loops.list`: What is pending, for whom, since when
- `state.commitments.list`: What the user committed to, and to whom
- `state.people.list`: People the user works with, with confidence
- `state.people.get`: One person: role, open items, last contact, evidence
- `state.projects.list`: Projects and their state
- `state.projects.get`: One project: people, commitments, open loops
- `memory.get_context_pack`: Budgeted pack: High as fact, Medium as "possibly", Low excluded
- `memory.recall`: Scoped recall for a task or a person
- `memory.search`: Federated search over events and state
- `memory.get_context`: Context around one event
- `memory.get_events`: Raw events in a window
- `memory.read_session`: One session's turns
- `memory.get_wrap`: A period's summary
- `memory.get_periods`: Which periods have summaries
- `calendar.upcoming`: What is on the calendar next
- `profile.whoami`: Who the principal is and what this key may do
- `wiki.evidence`: The verbatim quotes behind a fact
- `actions.status`: Where an L2/L3 action stands

### Writes · L1 · metered

- `memory.ingest`: Conversation turns, tool results, task progress. Idempotency key required
- `memory.append_note`: The agent's own note, kept as an event

### Actions · L1/L2/L3 by action kind

- `actions.execute`: Run an action. Reads run; user-data writes return input_required; sends return an approval URL

### Router · no key needed for discover and inspect

- `discover`: Candidates for a task with score breakdown, price, p50/p95 and a first_party label
- `inspect`: Schema, price, examples and hints for one tool
- `run`: Run a tool under L1/L2/L3 and keep the result as state. Takes idempotency_key and dryRun

## Pricing

Reads are free. You pay for what you ingest and what you run. No subscription, prepaid credits, 402 when exhausted, per-key and per-agent hard caps from day one.

| Metered item | Unit price | Notes |
|---|---|---|

| State reads (state.*, get_context_pack, recall, search) | $0 | Metered for observability, never billed |
| Remote L2/L3 approvals | $0 |  |
| Local (open source) | $0 | Same API; switch baseURL |
| Ingest | $0.50 / 1K events | Includes extraction LLM cost |
| Model-invoking op | $0.10 / 1K | Consolidation, AI search, entity pages |
| Tool run, first-party connector | $0.002 / call | Writes pass L2/L3 at the same price |
| Tool run, third-party provider | provider price + 5% | Failures and empty results $0 |
| Hosted storage | $0.10 / GB-month | Delete and export always free |
| Enterprise | same rates, 10–25% off with annual commit | BYOC / ZDR / SSO / audit included; no seat fees |

All prices are estimates and will be revised from design partners' real usage. Failed and empty results cost nothing. Delete and export are always free.

## Runs everywhere

### On your laptop
The open-source engine, MCP / REST / CLI on loopback, one SQLCipher file per principal. $0. Nothing leaves the device.

### Hosted
The same API behind api.shogunagent.com. Sync a second device or agent, top up a wallet, approve L3 actions from the web or Slack. Bodies are relayed, never stored.

### In your cloud
BYOC, zero data retention, SSO / SCIM, audit export. Same rates, no seat fees.

## Not a memory API

Memory APIs (Mem0, Zep, Letta, supermemory, Cognee) store free text in a vendor cloud and expose read/write. Routers and registries have no permission tiers and no state. ShogunAgent is the system of record underneath both.

| | Memory APIs | ShogunAgent |
|---|---|---|

| Unit of storage | Free-text facts, embeddings | Typed rows with quote, confidence and supersession |
| Permission model | Read / write | L1 / L2 / L3 by action type, same for every agent |
| Where data lives | Vendor cloud | The device by default; hosted path keeps no bodies |
| Engine | Closed; clients open at best | Apache-2.0 |
| Leaving | Export varies | Open export format; delete and export free |
| Reads | Billed | Free |

## Open source

**Open (Apache-2.0):** The engine (state tables, confidence, consolidator, Dream Cycle), local MCP / REST / CLI, connector definitions and the router engine, SKILL.md, the export format, all six eval harnesses.

**Closed:** Hosted sync, remote approvals, wallet and billing, the hosted router catalog and provider contracts.

No telemetry by default. Opt-in only, counts only, never content.

Repository: https://github.com/Torutesu/Shogunagent

## FAQ

### Is this a memory API?
No. Memory APIs answer "what did the agent see". ShogunAgent answers "what is true now": who owes whom what, which loops are open, with a quote behind every row. It can sit behind Anthropic's memory tool as storage, and it ingests from Mem0-style free text, but the product is the typed state.

### Can an agent start without a human?
Yes. discover, inspect and a tightly scoped read need no key. POST /v1/agents returns a scoped key and the free allowance with no email. The first metered call returns 402 with everything needed to proceed. The only human step is attaching a card, once.

### What can an agent never do?
Send, post, pay or create calendar events without a human approving at a URL. That is L3 by type, and the router denies any operation that is not in its scope table.

### Which model does it use?
It is model-agnostic. Our own LLM use is extraction and consolidation only, in cheap batch lanes. Your agents bring their own model.

### Where is it today?
Pre-release. About 330k lines of Rust migrated from ShogunAI build and test on Linux. Phase 1 (Streamable HTTP MCP with the frozen core tools, API-key auth, /memories projection, export v1, router skeleton, 402 and the agent-readable surfaces) is in progress. Watch the repo.