Docs

Hermit is one memory for your AI agent, reachable over MCP and a REST API. Set it up once; every model you switch to reads the same facts, decisions and file map.

The app opens soon. These docs describe Hermit at launch. About the app →

Setup

Claude Code, one line:

$ claude mcp add --transport http -s user hermit https://hermit.example/mcp

Hermit is a remote MCP server, so there is nothing to install. -s user makes it available in every project, not just the current folder.

Then run /mcp in Claude Code and choose hermit → Authenticate. Your browser opens Hermit:

  1. Sign in with GitHub or a Solana wallet. Either one works; see Sign-in below.
  2. Allow access. Hermit shows which app is asking and where it sends you back. Allow lets that app read and write your memory.
  3. Back to the terminal. Claude Code keeps the access token and renews it on its own.

With an API key instead

For a client without sign-in, a server or CI: create a key in the app under Keys. It is shown once. Send it as a header:

$ claude mcp add --transport http -s user hermit https://hermit.example/mcp \
    --header "Authorization: Bearer $HERMIT_KEY"

Sign-in

An account is a GitHub identity, a Solana wallet, or both. There is no email and no password.

GitHub

Choose Continue with GitHub and approve. Hermit asks only for the read-only read:user scope and uses two things from your profile: your GitHub user id, which is your account, and your login, which it shows in the app. No email, and no access to your repositories. GitHub's access token is used once to read that and is never stored.

Both

In the app under Account you can add the other one: link a wallet to a GitHub account, or connect GitHub to a wallet account. Both then open the same account. A wallet or GitHub account that already has its own Hermit account can't be added to another one; accounts are never merged.

Solana wallet

Phantom, Solflare, Backpack or MetaMask. You sign one message that proves the address is yours. It is not a transaction and costs nothing.

When you need a wallet

Only to burn $HRMT for credit, because a burn is a transaction your wallet signs. Everything else, including the free monthly credit, works with GitHub alone.

Other clients

Every client uses the same URL: https://hermit.example/mcp

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "hermit": { "url": "https://hermit.example/mcp" }
  }
}

Then open Cursor Settings → MCP and sign in to hermit.

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "hermit": { "httpUrl": "https://hermit.example/mcp" }
  }
}

Then sign in: /mcp auth hermit

Codex

Add to ~/.codex/config.toml:

[mcp_servers.hermit]
url = "https://hermit.example/mcp"

Then sign in: codex mcp login hermit

Claude Desktop and claude.ai

Settings → Connectors → Add custom connector, paste the URL above, then Connect to sign in.

ChatGPT

On the web: Settings → Apps & Connectors → Advanced settings, turn on Developer mode. Then create a connector, paste the URL above, choose OAuth and sign in.

Local models

Hermit is a remote server, so a local model reaches it through any MCP client that connects to remote HTTP servers, with the same URL, or through the REST API from your own code. hermit_context sends a digest of about 1,500 tokens once a project grows; set max_tokens lower for a small context window. Memory text goes only to the model that reads it, so with a local model it stays between Hermit and your machine.

Tools

Hermit gives your agent seven tools. Its instructions tell the agent to load the project's memory at the start of a session and to save lasting facts and decisions as it works, never secrets. You don't have to ask.

  • hermit_context — the project's memory at the start of a session: all of it while it is small, a digest of pinned and newest lines after that
  • hermit_remember — save one fact, decision, file, preference or note
  • hermit_recall — search by keywords, in one project or across all of them
  • hermit_update — change a memory's text or kind, pin or unpin it
  • hermit_forget — delete one memory
  • hermit_projects — list your projects, team projects as team/project
  • hermit_import — turn a rules file into memories (see Import)

A project is named after the repo or folder and is created on its first write. A memory holds up to 2,000 characters and remembers which model wrote it. Agents refer to memories by short ids like [3f9a1c2e].

Import

Already keep instructions for your agent in a file? Import it and Hermit turns it into memories, one rule or fact each, that every model reads, not only the editor the file was written for.

  • CLAUDE.md — Claude Code
  • AGENTS.md — Codex and other agents
  • .cursorrules — Cursor
  • .windsurfrules — Windsurf
  • any .md or .txt notes, up to 200 KB

Each bullet, numbered item or short paragraph becomes one memory; the heading above it is kept as context (Testing: run npm test before pushing). Code blocks are skipped. Hermit guesses the kind: decision for things like “we use X because…”, preference for style, tone and tooling rules, file when it names a path like src/…, otherwise fact. Secrets in the file become [redacted] before anything is written, like every other write, and lines you already have in the project are skipped.

In the app

Open a project, choose Import, then pick the file or paste it. You see every memory it would create, with a checkbox and its kind, before anything is saved. Untick what you don't want, change a kind, and choose Import.

What it costs

The preview costs one read. Each saved memory costs one write, the same as an agent's hermit_remember; the app shows the total before you save. An import is all or nothing: if your credit doesn't cover every memory, none are saved. Up to 300 new memories per import.

With the API

$ curl -X POST "https://usehermit.xyz/api/v1/projects/my-app/import" \
    -H "Authorization: Bearer $HERMIT_KEY" \
    -H "Content-Type: application/json" \
    -d "$(jq -n --rawfile t CLAUDE.md '{text: $t, filename: "CLAUDE.md", dryRun: true}')"

POST /projects/{slug}/import takes text (the file's contents, up to 200 KB), an optional filename (shown as “learned by import · CLAUDE.md”), and an optional dryRun. With dryRun: true it returns the memories it would create and writes nothing (one read); send it again without dryRun to save the new ones (one write each). The answer:

{
  "dryRun": true,
  "project": { "ref": "my-app", "exists": true },
  "items": [
    { "text": "Code style: Use 2 spaces", "kind": "preference",
      "context": "Code style", "redacted": false, "duplicate": false }
  ],
  "counts": { "found": 12, "new": 11, "duplicates": 1, "redacted": 0, "overCap": 0 },
  "cost": { "perItem": 0.05, "total": 0.55 }
}

A save returns the same plus saved and the new memory ids. Agents can do the same with the hermit_import tool (project, text, optional filename); it saves right away.

Teams

A team shares memory. Projects in a team are read and written by every member's agents; your personal projects stay private to you.

  • Create a team in the app and give it a name. You are its owner.
  • Invite people with a link. A link works for 7 days, for one person or a set number; an owner can revoke it at any time. The person signs in with GitHub or a wallet and joins as a member.
  • Members read, write, edit and forget memories in the team's projects and can start new ones. Owners also invite and remove people, change roles, move a personal project into the team, delete team projects and delete the team.
  • Removing someone takes their access away at once, including their agents' keys and sign-ins.
  • Each memory still records who wrote it and with which model.

Naming team projects

Agents name a team project team/project, for example hermit_context {"project": "acme/api"}, the same way in every tool. Your personal projects keep their plain names. A name like owner/repo only means a team project when you are a member of a team called owner; otherwise it is a personal project, as before. hermit_projects lists team projects by their full name.

In the REST API add ?team=acme to any project path: GET /projects/api/context?team=acme. acme%2Fapi in the path works too. GET /teams lists your teams.

Who pays

The team owner. Every read and write in a team project, by any member's agent, over MCP, the REST API, the app or an import, is charged to the owner's credit. If the owner's credit runs out, members get a clear message to ask the owner to add credit (402 team_out_of_credit). Members' personal projects stay on their own credit, and so do account-wide calls like hermit_projects and a recall across all projects.

In the app, team projects are grouped under their team and show the name your agents use for them.

REST API

For your own code, or anything without MCP. Base URL: https://hermit.example/api/v1

Send a key from the app as Authorization: Bearer <key>. An access token from an MCP sign-in works too.

$ curl "https://hermit.example/api/v1/projects/my-app/context?budget=auto" \
    -H "Authorization: Bearer $HERMIT_KEY"
$ curl -X POST "https://hermit.example/api/v1/projects/my-app/memories" \
    -H "Authorization: Bearer $HERMIT_KEY" \
    -H "Content-Type: application/json" \
    -d '{"kind": "decision", "text": "Deploy on push to main"}'
  • GET /me — your account and credit
  • GET /projects — projects with memory counts and the last write
  • GET /projects/{slug}/context?budget=auto|full|digest — what hermit_context returns
  • GET /projects/{slug}/memories?q=&kind=&limit= — list or search memories
  • POST /projects/{slug}/memories — add one: kind, text, optional model and pinned
  • PATCH /memories/{id} — change text, kind or pinned
  • DELETE /memories/{id} — forget one memory
  • GET /projects/{slug}/export?format=json|md — a whole project, as JSON or Markdown
  • POST /projects/{slug}/import — import a CLAUDE.md, AGENTS.md or .cursorrules file (see Import)
  • DELETE /projects/{slug} — delete a project and all its memories
  • GET /teams — your teams and your role in each

Every /projects/{slug} path takes ?team=<team> for a team project (see Teams).

Errors are JSON: {"error": {"code", "message"}}. 401 means a missing or revoked key, 402 means out of credit, 429 means more than 120 requests a minute (wait for Retry-After). Calls cost the same as over MCP.

What is stored

Stored

  • What your agent saves, or you add in the app: facts and decisions like “pnpm, not npm” and “deploy on push”, preferences and conventions.
  • File notes: a path and a one-line purpose, not the file's contents.
  • For each memory: its project and kind, which model wrote it, and when.
  • Your account: your GitHub user id and login, your wallet address, or both. Monthly read and write counts for credit.

Never stored

  • Your files. Hermit can't see your disk or repo; it only gets what the agent sends it.
  • Secrets. API keys, tokens, private keys and secret .env values become [redacted] before anything is written.
  • Full chat transcripts.
  • Your API keys and access tokens in plain text: only their hashes, so a key is shown once.
  • Your wallet's private key or seed phrase. Hermit never asks for them.

Encryption

Memory text is encrypted at rest with AES-256-GCM and bound to your account. The server decrypts it only to answer your own requests, so it is encryption at rest, not end-to-end.

Export and delete

Export a project as JSON or Markdown from the app or the API. Forgetting a memory erases its text at once; deleting a project removes it with all its memories. The full policy is on the Privacy page.

Credit

There are no plans or seats. Every account gets free credit each month; past that, you burn $HRMT and the burn becomes credit.

Free allowance

50 credits a month, renewed on the 1st (UTC). Unused free credit doesn't carry over, and it is spent before burned credit.

What a call costs

  • A read (hermit_context, hermit_recall, hermit_projects, API reads): 0.01 credit
  • A write (hermit_remember, hermit_update, API writes): 0.05 credit; an import costs one write per saved memory
  • In a team project, reads and writes are paid by the team owner (see Teams)
  • Free: hermit_forget, deleting, export and GET /me

The free allowance alone covers about 5,000 reads or 1,000 writes a month. A call that fails costs nothing. Browsing and pinning your memory in the app is free; adding or editing a memory there costs a write, like an agent’s. When credit runs out, the agent gets a clear “out of credit” message with a link to the app.

Burn for credit

  1. Buy $HRMT on Solana. Check the full mint address below; copies with the same name exist.
  2. Burn in the app. Open Credit, connect your wallet if you signed in with GitHub, enter an amount and approve one SPL token burn. The tokens are destroyed on Solana, not sent to any address, and the app never holds them.
  3. Credit for your agent. Once the transaction is finalized on Solana, the app checks it on chain and adds 1 credit per $HRMT burned to your account. Burned credit never expires.

Closed the page before the credit showed up? Paste the transaction signature under “Claim a past burn” on the Credit page. Only burns signed by your account's wallet count, and each one is credited once.

Token mint — don't send tokens here

Burns happen only in the app, and they are permanent. Never send tokens to the mint address, or to anyone who messages you.

FAQ

Does a small model see everything?

No. Past about 1,500 tokens, hermit_context sends a digest: pinned lines first, then the newest of each kind. The agent finds the rest with hermit_recall.

Which models work?

Anything behind an MCP client: Claude, ChatGPT and Codex, Gemini, local models. Your own code can use the REST API.

Do I need $HRMT to start?

No. Signing in is free, and the monthly allowance is enough to try Hermit on real projects.

Is there a subscription?

No. Past the free allowance, credit comes only from burns, and it does not expire.

Can I take my memory elsewhere?

Yes. Export a project as JSON or Markdown from the app, or with GET /projects/{slug}/export.

Do I need a wallet?

No. GitHub sign-in is enough for everything except burning $HRMT.

What if I lose my wallet?

If your account also has GitHub, sign in with that. If the wallet was your only sign-in, you can't open the app without it, but API keys you already made keep working, so you can still export your memory with one.

What if Hermit is down?

Your agent keeps working without memory until Hermit is back; nothing saved is lost. See the status page.

Which token is the real one?

Only the one shown on this site. Compare the full mint address, not just the last few characters.