Docs — Mimesis

1

Create your memory

Sign up and you get a private, per-user memory store immediately — nothing to install for the hosted beta. Create your memory →

2

Connect an assistant over MCP

Point any MCP-speaking client — Claude, an agent you run yourself, anything that talks the protocol — at the Mimesis MCP server. It runs over stdio and exposes mimesis_context, mimesis_remember, mimesis_propose_memory, candidate approve/reject, and explain.

Know which memory you're connecting to: the stdio MCP server reads and writes a local memory on that machine (a clone of the open-source engine). Your hosted mimesis.ai account is reached over the HTTP API with your bearer token — an MCP connection does not see it.

# one-time, on the machine the assistant runs on:
$ git clone https://github.com/RevBooyah/mimesis-ai.git ~/mimesis-ai

// mcp client config, e.g. claude_desktop_config.json
{
  "mcpServers": {
    "mimesis": {
      "command": "python3",
      "args": ["-m", "mimesis.mcp_server", "--user", "you", "--agent", "claude"],
      "env": { "PYTHONPATH": "/home/you/mimesis-ai/src" }
    }
  }
}

PYTHONPATH must be the absolute path to the clone's src/ — a relative src only works if the client happens to launch from the repo root.

Works with

Your memory shows up wherever your agents run.

Mimesis speaks the Model Context Protocol (MCP) and a plain HTTP API, so it plugs into any MCP-capable assistant, editor, or multi-agent system. One memory, the same across all of them.

Multi-agent systems & agent OSs

HermesOpenClawClaude CoworkGoose

Hermes also has native importers for its sessions and memory (see below).

Assistants & editors

Claude CodeClaude DesktopCursorVS CodeClineWindsurfZed

Or anything that speaks MCP

If your tool can call an MCP server, it can read from your memory — including agent frameworks like LangGraph, CrewAI, and the Microsoft Agent Framework that call it as a tool.

The list isn't fixed: if a host lets its agents call MCP tools, Mimesis works there, and it grows as MCP support spreads. Mimesis holds the memory; you point the tool at it.

3

Talk to it over HTTP

Every request carries the bearer token you got back from signup or login. POST /api/context compiles a prompt-aware briefing, sized to the token budget you set. The /api prefix is the hosted-beta path; running your own server, drop it and call /context directly.

$ curl -X POST "$MIMESIS_HOST/api/context" \
  -H "Authorization: Bearer $MIMESIS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "prep me for the supply-chain review", "max_context_tokens": 1200}'

4

Review what it learns

Anything an assistant infers about you arrives as a candidate, not a fact. Keep it, edit it, or discard it in the app — or pull the queue directly and approve or reject by id.

$ curl "$MIMESIS_HOST/api/candidates" -H "Authorization: Bearer $MIMESIS_TOKEN"

Connecting as an agent (read this if you are one)

Everything an AI agent needs to connect a human's hosted mimesis.ai account, or to walk them through it. Machine-readable copy of this reference: /llms.txt.

1 · Get a token

The easy way (tell your human this): log in at mimesis.ai → My account → Agents tab → Connect an agent → name the agent → Create token. The token is shown once with a copy button — paste it into the agent's config. Agent tokens last 90 days and can be revoked from the same card.

The programmatic way: accounts belong to humans — if yours doesn't have one, walk them through signup rather than inventing credentials. Signup/login return a session token directly, and an authenticated call to POST /api/auth/token {"agent":"hermes"} mints a dedicated 90-day agent token (recommended over reusing the login session — revoking one doesn't kill the other).

# new account (password ≥ 12 chars; email required for recovery)
$ curl -X POST https://mimesis.ai/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"user":"stevec","email":"steve@example.com","password":"a long passphrase"}'

# existing account ("user" or "email" + password)
$ curl -X POST https://mimesis.ai/api/auth/login \
  -d '{"user":"stevec","password":"a long passphrase"}'

# both return:
{"user":"stevec", "email":"…", "agent":"…", "token":"mt_…"}

Treat the token like a password: send it only as a header, never store it in a memory (obvious credentials are refused at the door anyway). Rate limits: signups and failed logins are capped per address — a 429 means wait, not retry.

2 · Call the API

Every request: Authorization: Bearer <token>. The token decides whose memory you touch — any user field in a request is ignored, so you cannot cross tenants.

POST /api/context	the main read: {"prompt":"…","max_context_tokens":1200,"budget_mode":"adaptive"} → a compiled briefing sized to your window
POST /api/propose-memory	{"text":"…","rationale":"why it matters"} → lands as a candidate for the human to keep or discard. This is how agents write.
POST /api/remember	{"text":"…"} → durable memory immediately. Only for words the human explicitly dictated — inferred facts go through propose-memory
GET /api/candidates	the review queue; approve/reject with POST /api/candidates/<id>/approve\|reject (only when the human says so)
POST /api/memories/search	{"query":"…","limit":20} → direct search when you need a specific fact, not a briefing
GET /api/profile	the owner's always-relevant identity/preference facts
POST /api/auth/token	{"agent":"name"} → a dedicated 90-day agent token (shown once); GET /api/auth/tokens lists active tokens, POST /api/auth/tokens/<id>/revoke kills one
GET /api/account/export	everything, as data the human owns; POST /api/auth/logout revokes the calling token

Errors are consistent: 401 missing/expired token → re-login; 403 your permission profile can't do that; 402 paid-tier feature; 429 rate cap. Bodies carry {"error":"…"}.

3 · Behave like a guest

Mimesis is the human's memory, not yours. Propose, don't assert: inferred facts go in as candidates with a rationale, and the human decides what's true. Ask for a briefing per task instead of bulk-reading; the compiler exists so you don't have to.

Bring your existing notes

Import an Obsidian vault, a Honcho chat export, or recent Hermes sessions from the CLI. Imported items — like anything an agent infers — land as candidates for you to review, never as active memory on their own.

$ PYTHONPATH=src python3 -m mimesis.cli --user you \
  import-obsidian --vault "~/Documents/Obsidian Vault"

$ PYTHONPATH=src python3 -m mimesis.cli --user you \
  import-honcho-json export.json

$ PYTHONPATH=src python3 -m mimesis.cli --user you \
  import-hermes-sessions --since-last-run

Prefer the command line?

Run Mimesis entirely from the CLI, no server required. Commands run from the repo root with PYTHONPATH=src.

$ PYTHONPATH=src python3 -m mimesis.cli --user you init
$ PYTHONPATH=src python3 -m mimesis.cli --user you \
  context "some prompt" --debug

Hosted beta endpoints live under /api. Running Mimesis yourself instead? The CLI, HTTP server, and MCP server use these same request and response shapes on your own machine.

Connect your first AI in a few minutes.