# Knowledge Porridge for AI agents

Knowledge Porridge is a learning map you use with your human. It places them on a sourced map of a field (management is live), finds what they don't know they don't know, and plans what to learn next. You do the teaching through seven MCP tools; answers are graded against fixed keys, never by you. Free while in beta.

If your human uses Claude, ChatGPT or another app with connectors themselves, they should add https://knowledgeporridge.ai/mcp as a connector there instead (they sign in once, no key). This guide is for agents that run on their own.

## 1. Sign your human up (one request)

Ask your human for their email address first, then:

```
curl -s https://knowledgeporridge.ai/agent/signup -H 'Content-Type: application/json' -d '{"email": "HUMAN_EMAIL", "agent_name": "YOUR NAME"}'
```

- `agent_name` names you, for example `Claude Code` (letters, digits, spaces, _ and - only).
- The response holds `api_key`, shown once. Store it where only you can read it (for example a file with mode 600) and never print it.
- `sandbox` is the trial: 100 tool calls within 7 days. If it is `null`, trials ran out for today; `detail` says so, and the key works fully once your human confirms (step 4).
- No email is sent at signup.
- 409 `account_exists`: your human already has an account. Ask them to connect you through their own sign-in: https://knowledgeporridge.ai/connect

## 2. Call the tools

The MCP server is `https://knowledgeporridge.ai/mcp` (streamable HTTP, stateless). Send the key as `Authorization: Bearer <api_key>`.

Plain HTTP works immediately, no client setup and no initialize call needed:

```
curl -s https://knowledgeporridge.ai/mcp -H "Authorization: Bearer $KP_API_KEY" -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -H 'MCP-Protocol-Version: 2025-06-18' -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "start", "arguments": {}}}'
```

The reply may be an event stream; the JSON-RPC result is on the `data:` line. To add it as an MCP server for later sessions:

- Claude Code: `claude mcp add --transport http knowledge-porridge https://knowledgeporridge.ai/mcp --header "Authorization: Bearer $KP_API_KEY"`
- Codex: `codex mcp add knowledge-porridge --url https://knowledgeporridge.ai/mcp --bearer-token-env-var KP_API_KEY`

## 3. First task: onboard your human

1. Call `start` and follow its `next_action`. Every response says what to do next; lessons from `next` carry a `teaching_contract`: follow it.
2. Whys: ask your human which real situations in the next year make the subject matter to them. `next` proposes common ones: accept those that fit (`why`, `action: "accept"`, their `template_id`) and add their own with `action: "add"`. One why is enough to start; 3 to 5 is better. `horizon`, `cost` and `needs` are optional: ask, don't invent. Proposals you leave undecided do no harm.
3. Ask them to list, from memory, what they know about the subject and what they've only heard of. Save it with `self_map`. Never suggest terms first.
4. Placement: call `next`, show them the question and options exactly, ask how confident they are (1-5), then send their choice with `answer` (`choice` is the option's index, or -1 for "I don't know", which is always fine). Never answer for them. Repeat until `next` stops serving placement questions (about 20).
5. Call `map` to show their gaps, then `next` for the first lesson.
6. Before the session ends, tell your human about the confirmation email (step 4 below) and send it if they agree. A trial lasts 100 tool calls; a full placement and first lesson use about 50.

Tools: `start`, `next`, `answer`, `why`, `self_map`, `note` (insights, questions, and evidence of doing), `map`. Each tool's description has its arguments.

## 4. Unlock the account (your human clicks once)

```
curl -s -X POST https://knowledgeporridge.ai/agent/owner-confirmation -H "Authorization: Bearer $KP_API_KEY"
```

This sends your human one email with a Confirm button (and a "Not me, block" button). Once they confirm, the key has no trial limit and they are signed in to their map on the web. You can ask for at most one email a day.

If your human signs in on the website before confirming, your key stops working (a key made before the owner proved their inbox never survives their sign-in). They can create a new one under Account, API keys.

## 5. Status, errors and keys

- `GET https://knowledgeporridge.ai/agent/status` with your key: `state` is `trial`, `no_trial`, `trial_used`, `trial_expired`, `multi_network` or `confirmed`, and `detail` says what to do next.
- When the trial is over, tool calls return an error result whose text says what to do next. Nothing is lost.
- A trial key is for one machine: used from more than 3 networks, its trial stops until your human confirms.
- `POST https://knowledgeporridge.ai/agent/key/rotate` with your current key returns a new one and revokes the old.
- 429 means a limit was reached; `detail` and `Retry-After` say when to try again.

## Data and privacy

Your human's email, whys, answers, notes and progress are stored to run the service, in the EU. Knowledge Porridge never sees your conversation, only tool calls. Privacy policy: https://knowledgeporridge.ai/privacy