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.

Give every agent the same picture of your work: people, projects, commitments and unfinished tasks, with evidence behind each fact and human approval before external actions.

**Status:** Source available. Hosted access and package releases are not yet available.

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 | Not deployed |
| https://api.shogunagent.com/.well-known/agent-card.json | Signed A2A Agent Card | Cross-organization handoff and identity | Not deployed |
| https://api.shogunagent.com/openapi.json | OpenAPI 3.1 for the REST face | Code-generating agents | Not deployed |
| https://api.shogunagent.com/.well-known/pricing.json | Machine-readable rate card, free allowance, caps | Price comparison before the first call | Not deployed |
| https://api.shogunagent.com/.well-known/status.json | Live p50 / p95, error rate, incident history | Health-weighted ranking | Not deployed |
| https://api.shogunagent.com/health | Liveness and latency | Health-weighted ranking | Not deployed |
| https://api.shogunagent.com/v1/agents | Implemented agent registration with an abuse challenge, scoped keys and a free allowance | Onboarding without a form | Not deployed |
| https://api.shogunagent.com/v1/quote | Exact cost before committing; every metered call also takes `dryRun` | Budgeted agents refuse unknown costs | Not deployed |
| 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 | Source available |
| https://registry.modelcontextprotocol.io/servers/io.github.torutesu/shogunagent | Canonical entry in the MCP Registry | Where Claude Code, Cursor and gateways look first | Not listed |
| https://github.com/Torutesu/Shogunagent/blob/main/packages/sdk-ts | TypeScript client and agent-framework adapters | Read context before a turn and ingest what changed | Source available |
| https://github.com/Torutesu/Shogunagent/blob/main/packages/sdk-py | Python client and agent-framework adapters | Share context and typed handoffs across agents | Source available |
| https://github.com/Torutesu/Shogunagent/blob/main/docs/api/handoff.md | Typed agent-to-agent work handoffs | Continue a task with the relevant state and source evidence | Source available |

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

```
Read https://shogunagent.com/llms.txt and check for an existing ShogunAgent connection. Use it to recall relevant context before a task and save meaningful updates at checkpoints. If none is configured, explain the source-build setup from the repository; hosted access and npm/PyPI releases are not yet available. Reads are L1 and free. L3 external actions need human approval; never bypass an approval URL or claim an action happened before its status confirms it.
```

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

Implementation reviewed: 2026-10-27. Source revision: https://github.com/Torutesu/Shogunagent/commit/f3eaefaefa236c35fd5e3011da2f58cd00398b80. This is a source review, not a hosted-service release.

## Context delivery

### Context packs
Recall relevant facts and dated evidence before a task. Keep uncertain information separate.

memory.recall → facts + evidence + token budget

### Memory files
Expose people, projects and open work through a virtual memory filesystem.

/memories/people/…
/memories/open_loops.md

### Tools + handoffs
Use MCP, REST or CLI. Pass typed task context and source evidence to the next agent.

handoff.create → handoff.accept

## What it is

ShogunAgent turns agent updates and connected data into structured context about people, projects, commitments and open work. Agents retrieve facts with source evidence through budgeted recall, virtual memory files, or tools over MCP, REST and CLI. Typed handoffs carry task context to another agent. Consequential external sends wait for human approval. The source is available; the hosted service and package releases are not yet public.

Saving history is only the first step. An agent also needs to know what is still pending, which facts are uncertain and where to check the evidence. ShogunAgent adds that structure so agents can act with context and people can review their reasoning.

### Start with the right context
Read the people, projects, commitments and open loops relevant to the task. A token budget keeps recall focused. High-confidence facts and uncertain information are presented separately.

*Proof in the code:* The recall path includes source evidence, marks Medium-confidence facts as possibly, and excludes Low-confidence facts from the context it assembles.

### Carry work across agents
Ingest useful updates at checkpoints. A typed handoff carries the task, relevant state and supporting evidence to the next agent, without mixing its scratch notes into the user’s shared state.

*Proof in the code:* handoff.create assembles the task context; handoff.accept validates it and ingests it into the receiving agent’s scratch namespace.

### Keep people in control
Read without an approval prompt. Confirm changes that need it. Queue external messages for human approval, and poll their status before reporting success.

*Proof in the code:* The core applies L1/L2/L3 permission checks across MCP, REST and CLI. Approval records preserve the decision and prevent a retry from executing the same approved action twice.

## Three faces, one behavior

Use MCP from an agent client, REST from your application, or the local shogun CLI. The core shares permission checks and response semantics across all three. These examples target a source-built local server; they are not calls to a public hosted API.

MCP:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "memory.recall",
    "arguments": {
      "query": "What is still pending?",
      "budget_tokens": 1200
    }
  }
}
```

REST:

```sh
curl -s http://127.0.0.1:7464/v1/memory/recall \
  -H "Authorization: Bearer $SHOGUN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"What is still pending?","budget_tokens":1200}'
```

CLI:

```sh
shogun recall "What is still pending?" --budget-tokens 1200 --json
```

Response metadata (illustrative values; see the tool schema for the result body):

```json
{
  "usage": {
    "unit": "read",
    "quantity": 1,
    "cost_micro_usd": 0
  },
  "latency_ms": 12,
  "next_action": null
}
```

A configured hosted gateway answers 402 when credits are insufficient (illustrative response):

```http
HTTP/1.1 402 Payment Required

{
  "error": {
    "code": "payment_required",
    "next_action": "top_up"
  },
  "payment": {
    "amount_micro_usd": 500,
    "unit": "ingest",
    "accepts": [
      {
        "rail": "card",
        "url": "https://YOUR_DEPLOYMENT/v1/wallet/topup",
        "method": "POST"
      }
    ],
    "retry_after": 0
  },
  "usage": {
    "unit": "ingest",
    "quantity": 0,
    "cost_micro_usd": 0
  }
}
```

An external send queues for approval (illustrative response, not an executed action):

```json
{
  "resultType": "approval_required",
  "approval": {
    "approval_id": 7,
    "level": "L3",
    "url": "https://YOUR_DEPLOYMENT/approve/EXAMPLE",
    "poll": {
      "tool": "actions.status",
      "arguments": {
        "approval_id": 7
      }
    }
  }
}
```

## Permission tiers

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

| L1 | Read and local ingest | Reads and allowed local ingest run immediately. Ingest is metered separately from free reads. | state.*, memory.recall, memory.ingest, memory.append_note | readOnlyHint for reads; write annotations for ingest | Reads free; ingest per event |
| L2 | Write to the user's data | Changes such as editing state require confirmation. MCP returns input_required and accepts inputResponses on retry. | state edits and other tools classified L2 | destructiveHint; confirmation required | Depends on the operation |
| L3 | Act on the world | External sends queue for explicit human approval. Poll actions.status; a pending request is not a completed action. Payment mandates require human approval; the current payment rail is a stub and moves no money. | send_email, post_message, post_comment | openWorldHint; approval_required | Approval request free |

## Tools

The implementation has 21 frozen core tools, plus router tools and typed handoffs. The names below match the source implementation. These are source-build capabilities; the hosted service is not yet public.

### Reads · L1 · free

- `state.open_loops.list`: Unresolved items with confidence and the source quote; filter by limit and offset
- `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 by id, with confidence and evidence-source references
- `state.projects.list`: Projects and their state
- `state.projects.get`: One project by id, with confidence and evidence-source references
- `memory.get_context_pack`: Grounded context for a query; use memory.recall for an explicit token budget
- `memory.recall`: Scoped recall for a task or a person
- `memory.search`: Federated search over events and state
- `memory.get_context`: Current captured device context; empty without a capture source
- `memory.get_events`: Raw events in a window
- `memory.read_session`: One session's turns
- `memory.get_wrap`: Today’s wrap-up: outcomes, open items and tomorrow’s first tasks
- `memory.get_periods`: Stored summaries for a time window; open their sources before quoting
- `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`: Poll an external-action approval; report success only when status is sent

### 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 · permission checked

- `actions.execute`: Run local_search or queue an external send for human approval; check actions.status before claiming completion

### Router · discover, compare and run

- `router.discover`: Candidates for a task with score breakdown, price, p50/p95 and a first_party label
- `router.inspect`: Schema, price, examples and hints for one tool
- `router.run`: Run a selected tool with permission checks, idempotency and a cost quote

### Handoff · continue work across agents

- `handoff.create`: Assemble a task with relevant state, confidence bands and source evidence; free read
- `handoff.accept`: Validate a received handoff and store it in the receiving agent’s scratch namespace; ingest pricing

## Pricing

Read state and recall context for free. In a hosted deployment, ingest, model operations, tool runs and storage use metered credits with spending caps. The source-build engine has no software subscription.

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

| State reads and recall | $0 | Also includes creating a handoff |
| Local engine | $0 | Apache-2.0 software; your infrastructure and model costs are separate |
| Ingest | $0.50 / 1K events | Includes agent updates and accepted handoffs |
| Model operations | $0.10 / 1K | Metered operations classified by the gateway |
| First-party connector runs | $0.002 / call | State reads remain free; no additional percentage |
| Third-party tool runs | Provider price + 5% | Charged once through the wallet |
| Hosted storage | $0.10 / GB-month | Export and deletion are free |
| Approval requests | $0 | Queuing an external action does not execute it |

Hosted rates shown are launch estimates taken from the gateway pricing implementation. Hosted billing is not yet publicly available. Quotes and receipts report costs in micro-USD; refused calls, errors and idempotent replays are not charged again.

## Ways to use it

### Run from source
Build the Rust engine and run it locally on Linux or macOS. Each principal has a separate encrypted store. Feed it agent updates or connected data; device capture requires the ShogunAI Mac app.

### Integrate your agents
TypeScript and Python clients include framework adapters for context recall, checkpoint ingest and handoffs. CLI and SDK code is in the repository; npm and PyPI packages are not yet published.

### Host on your infrastructure
Deployment configurations include Compose and Helm, with a gateway and per-principal core service. Enterprise controls are implemented in source; operating the stack requires your infrastructure, credentials and provider setup.

## Beyond saved history

A saved transcript tells an agent what was said. Structured state helps it find what is still relevant: who is involved, what is unresolved and which source supports a claim. Keep the history for evidence, and use the state for the next task.

| | Stored history | ShogunAgent |
|---|---|---|

| Working unit | Messages and source events | People, projects, commitments and open loops |
| Uncertainty | Wording must be interpreted again | Confidence bands; uncertain facts marked explicitly |
| Verification | Read the original history | Follow evidence back to its source event |
| Continuity | Send another transcript | Ingest updates or pass a typed task handoff |
| Control | Stored context alone does not approve actions | Permission checks and a human approval queue |

## Open source

**Open (Apache-2.0):** Apache-2.0 source for the state engine, local MCP / REST / CLI, router, connector definitions, SDKs, handoffs and export/import tools. Export formats preserve state and evidence so you can move your data.

**Hosted availability:** The public hosted service is not yet available. Hosted sync, managed billing and provider operations describe a deployment model, not a service you can subscribe to today.

The server defaults to no telemetry. Optional analytics are counts only, not stored content.

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

## FAQ

### What can I use today?
The source repository contains the engine, MCP/REST/CLI interfaces, SDKs, router, connector integrations and deployment configurations. Build and run the components you need. Public hosted access, npm/PyPI releases and directory listings are not yet available.

### How does an agent get started?
Read llms.txt and look for an existing configured connection. With a source-built server running, recall context before a task and ingest useful updates at checkpoints. The CLI can configure read-only MCP connections for supported clients; review its source-build instructions before using it.

### What does this do for the person using the agent?
You spend less time repeating context. Agents can pick up the same work, show the evidence behind a commitment and ask for approval before an external send. You can inspect, correct and export the underlying state.

### Can one agent hand work to another?
Yes. The implemented handoff.create tool assembles task context with source evidence and confidence bands. handoff.accept validates it and stores it in the receiver’s scratch namespace rather than silently changing shared world state.

### Which models and frameworks does it support?
Agents bring their own model. TypeScript and Python adapter source covers the OpenAI Agents SDK, Claude Agent SDK and LangGraph; TypeScript also covers Vercel AI SDK and Mastra, and Python includes CrewAI. These are integrations in the repository, not published packages.

### How are permissions and payments handled?
Reads run without approval. L2 operations ask for confirmation; external sends queue as L3 for human approval. Payment mandates are implemented, but the current rail is a stub that moves no money. This site does not accept payments or activate hosted access.

### Does it send embeddings or raw context to a cloud service?
Search is keyword-first, with optional local embeddings. Embeddings do not go to a cloud API. Extraction and consolidation depend on your configured model path; review that configuration before ingesting sensitive data. The hosted gateway is designed to relay bodies without persisting them.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "memory.recall",
    "arguments": {
      "query": "What is still pending?",
      "budget_tokens": 1200
    }
  }
}

curl -s http://127.0.0.1:7464/v1/memory/recall \
  -H "Authorization: Bearer $SHOGUN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"What is still pending?","budget_tokens":1200}'

shogun recall "What is still pending?" --budget-tokens 1200 --json

{
  "usage": {
    "unit": "read",
    "quantity": 1,
    "cost_micro_usd": 0
  },
  "latency_ms": 12,
  "next_action": null
}

HTTP/1.1 402 Payment Required

{
  "error": {
    "code": "payment_required",
    "next_action": "top_up"
  },
  "payment": {
    "amount_micro_usd": 500,
    "unit": "ingest",
    "accepts": [
      {
        "rail": "card",
        "url": "https://YOUR_DEPLOYMENT/v1/wallet/topup",
        "method": "POST"
      }
    ],
    "retry_after": 0
  },
  "usage": {
    "unit": "ingest",
    "quantity": 0,
    "cost_micro_usd": 0
  }
}

{
  "resultType": "approval_required",
  "approval": {
    "approval_id": 7,
    "level": "L3",
    "url": "https://YOUR_DEPLOYMENT/approve/EXAMPLE",
    "poll": {
      "tool": "actions.status",
      "arguments": {
        "approval_id": 7
      }
    }
  }
}