# ShogunAgent

> The state layer for AI agents. 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.

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.

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

Rules an agent should know before calling anything: reads are L1 and free; writes to the user's data are L2 and return `input_required`; sending, posting and paying are L3 and return an approval URL for a human. Every write takes an idempotency key. Every response carries `usage`, `latency_ms` and, on error, `next_action`.

## Read first

- [/llms.txt](https://shogunagent.com/llms.txt): Agent-readable index of this site and the API
- [/llms-full.txt](https://shogunagent.com/llms-full.txt): Everything on this site as one Markdown document
- [/index.md](https://shogunagent.com/index.md): This page as Markdown. Also what `Accept: text/markdown` returns for `/`
- [/setup-prompt.txt](https://shogunagent.com/setup-prompt.txt): The one-paragraph prompt a human pastes into their coding agent
- [README](https://github.com/Torutesu/Shogunagent#readme): strategy, pillars, pricing and roadmap in full (English and Japanese)
- [Implementation plan](https://github.com/Torutesu/Shogunagent/blob/main/docs/implementation-plan.md): epics, tasks and acceptance criteria

## Tools (core wire names, frozen)

- Reads · L1 · free: `state.open_loops.list`, `state.commitments.list`, `state.people.list`, `state.people.get`, `state.projects.list`, `state.projects.get`, `memory.get_context_pack`, `memory.recall`, `memory.search`, `memory.get_context`, `memory.get_events`, `memory.read_session`, `memory.get_wrap`, `memory.get_periods`, `calendar.upcoming`, `profile.whoami`, `wiki.evidence`, `actions.status`
- Writes · L1 · metered: `memory.ingest`, `memory.append_note`
- Actions · L1/L2/L3 by action kind: `actions.execute`
- Router · no key needed for discover and inspect: `discover`, `inspect`, `run`

## Pricing

- 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)

## Phase 1 (planned, not live yet)

- [/.well-known/mcp/server-card.json](https://api.shogunagent.com/.well-known/mcp/server-card.json): MCP Server Card: endpoint, auth, tool list with annotations
- [/.well-known/agent-card.json](https://api.shogunagent.com/.well-known/agent-card.json): Signed A2A Agent Card
- [/openapi.json](https://api.shogunagent.com/openapi.json): OpenAPI 3.1 for the REST face
- [/.well-known/pricing.json](https://api.shogunagent.com/.well-known/pricing.json): Machine-readable rate card, free allowance, caps
- [/.well-known/status.json](https://api.shogunagent.com/.well-known/status.json): Live p50 / p95, error rate, incident history
- [/health](https://api.shogunagent.com/health): Liveness and latency
- [/v1/agents](https://api.shogunagent.com/v1/agents): POST: agent self-registration. Returns a scoped key and the free allowance. No email
- [/v1/quote](https://api.shogunagent.com/v1/quote): Exact cost before committing; every metered call also takes `dryRun`
- [SKILL.md](https://github.com/Torutesu/Shogunagent/blob/main/SKILL.md): Trigger conditions, non-trigger exceptions, setup, auth, precedence, cost warnings, L2/L3 meaning
- [io.github.torutesu/shogunagent](https://registry.modelcontextprotocol.io/servers/io.github.torutesu/shogunagent): Canonical entry in the MCP Registry

## Optional

- [Repository](https://github.com/Torutesu/Shogunagent): Apache-2.0, Rust engine, MCP / REST / CLI
- [Setup prompt](https://shogunagent.com/setup-prompt.txt): paste into a coding agent