Connecting agents

Agents join the table over MCP, which gives them tools: remember, recall, ask. On the hosted app, an agent connects with a key or as a connector. On your own machine, hippo serve runs the same tools. Either way, an agent’s first call is onboard, which tells it who it is, and asks a stranger to introduce itself.

The tools

The curator has five more tools under the curate scope; see The curator. Two resources come with the read scope: hippo://handbook and hippo://entity/{slug}. Secrets are never revealed through any of them; see Secrets.

Tools outside a connection’s scopes are removed, so the client never even sees them.

A good session follows the server’s own instructions. Call onboard first. Use recall, get and ask_canon before acting on facts. remember anything worth keeping. Treat rumor as “verify first” and disputed as “don’t act without checking”.

On the hosted app

Agents connect to your vault’s address, https://<your-instance>/mcp, shown on the Setup page. They need a key, or, for Claude.ai and ChatGPT, a GitHub sign-in.

Keys

Mint keys under Setup → Connect agents. A key is shown once: copy it, or copy one of the snippets next to it, which already carry it. Only a hash is stored, so a lost key can’t be shown again; mint a new one. Revoke stops a key at once.

claude mcp add --transport http hippocampus https://<your-instance>/mcp --header "Authorization: Bearer hippo_…"

The Setup page also has snippets for .mcp.json, Cursor and VS Code.

The Claude Code plugin brings the server and a skill that teaches an agent how to use memory:

claude plugin marketplace add mehrad77/hippocampus
claude plugin install hippocampus@hippocampus
export HIPPO_MCP_URL=https://<your-instance>/mcp
export HIPPO_KEY=<your agent key>

Then /hippocampus:memory loads the habits: onboard first, read before acting, one memory per call.

Connectors (Claude.ai, ChatGPT)

In Claude.ai or ChatGPT, add a custom connector with the URL https://<your-instance>/mcp. The app asks you to sign in with GitHub, then shows a consent page for your vault:

• pick the agent id the app acts as: a party member, to give it that lane, or a new id, which you can seat in the party right away;
• choose what it may do: read and remember are ticked; quests and curating are yours to add. Curating shows the app every new memory in full, secret ones in plain text, so allow it only for an app you’d trust as the curator.

Your account menu lists connected apps, and disconnects any of them.

On your own machine

stdio, for local agents

One process per agent, bound to its id with --agent:

claude mcp add hippocampus -- npx -y @mehrad77/hippocampus -v ~/vaults/my-campaign serve --agent campus-agent

For Claude Desktop, add it to claude_desktop_config.json:

{
  "mcpServers": {
    "hippocampus": {
      "command": "npx",
      "args": ["-y", "@mehrad77/hippocampus", "-v", "~/vaults/my-campaign", "serve", "--agent", "home-finder"]
    }
  }
}

To serve a vault on GitHub without a checkout, replace -v ~/vaults/my-campaign with --github you/my-campaign, and put a fine-grained token (Contents: read and write, on that repo only) in HIPPO_GITHUB_TOKEN.

Local HTTP, for several agents at once

npx @mehrad77/hippocampus -v ~/vaults/my-campaign serve --http 8765

Each agent connects to http://127.0.0.1:8765/mcp?agent=<id>, for example:

claude mcp add --transport http hippocampus "http://127.0.0.1:8765/mcp?agent=job-scout"

It listens on 127.0.0.1 only and asks for no key, so any program on this machine can connect as any agent, curator tools included. Use it for agents you run yourself.

Inbox files, without MCP

A local tool that can’t speak MCP may write one new file per memory to inbox/<its-id>/<YYYY-MM-DDTHHMMSS>-<short-slug>.md, in the format the handbook shows, and must never touch other files. Everything else should use the tools: they run the checks, and the vault’s AGENTS.md tells agents not to edit files.

Which agent is speaking?

• Hosted app: a single-agent key’s agent, the connector’s chosen agent, or the agent argument with an agent key.
• stdio: --agent (or HIPPO_AGENT). Without it, the write tools require an agent argument.
• Local HTTP: ?agent= in the URL.
• Inbox files: the episode’s agent: property, which must match its folder.

Ids are exact: lowercase letters, digits and dashes, matching party/<id>.md. Your own id and the reserved ids human, curator, unknown and hippocampus are refused. See Party and lanes.

New agents introduce themselves

An id with no party sheet still works, but everything it reports counts as a rumor. onboard tells such an agent so, and asks it to call introduce:

{
  "agent": "job-scout",
  "title": "Job Scout",
  "lane": "Finds paid work in Lisbon and tracks applications. Stays out of housing and the permit.",
  "host": "Claude Desktop",
  "model": "the model it runs on",
  "about": "Searches job boards daily and keeps the application quest up to date."
}

The introduction waits for you on the Party page, and the Tavern lists it under what needs your attention. Approve seats the agent with the authority domains you pick; Dismiss removes the introduction. Introducing again replaces the earlier one.

Writing memories the curator gets right

The curator is only as good as what it’s given. The handbook gives agents the same advice:

• One memory per call. Short, concrete, self-contained.
• Name things. People, places and organizations by name, and links in about when you know them: ["[[residence-permit]]", "Agência de Migração"].
• Exact values. ISO dates (2026-10-14), amounts with currency (1,050 EUR), full IDs, emails and phone numbers.
• Say how you know when it matters: “confirmed by email”, “seen on the permit portal”.
• Corrections are new memories. “The appointment moved to…” Never edit old episodes.
• Pick a kind. fact, observation, decision, task (quest progress), beat (a story moment for the game master) or question.
• Mark secrets. secret: true whenever an ID, an account number or a password is involved.

A remember call, in full:

{
  "text": "The Migration Agency moved the residence-permit appointment to 2026-10-14 10:30 at the Alfama office. Bring passport, two photos and the signed lease.",
  "kind": "fact",
  "about": ["[[migration-agency]]", "[[residence-permit]]"]
}