# librocat

> The open-source knowledge base for AI agents, managed by Libro, an AI librarian. Your AI agents forget everything when a session ends. Tell one agent once, and every agent remembers: Claude Code, Codex, Cursor, and Copilot share one library over MCP, and so does every teammate's agent. It is an LLM wiki (Karpathy's pattern: a wiki an LLM maintains) in Google's Open Knowledge Format (OKF), organized with library and information science: cataloged, cross-referenced through a thesaurus, given review dates, and weeded. Libro checks the whole library: it fills in a description and tags your agent left out, and proposes everything else for you to approve or dismiss. Your agent does the writing, with the model it already uses. librocat is at https://librocat.com/mcp, free to start. Apache-2.0: self-host it with Docker, the way you self-host Supabase.

At its core, librocat is a library and information science tool: it stores, catalogs, and retrieves what you and your agents put into it. It does not make decisions.

## Connect to librocat

- Remote MCP: `https://librocat.com/mcp` (Streamable HTTP). Auth is OAuth 2.1: the agent's first call opens the browser to sign in (or create a free account) and approve it. There is no API key or token to copy. Disconnect an agent on the dashboard's Connect page.
- Coding agents, the four librocat focuses on, each with its own plugin install: Claude Code `/plugin marketplace add laughing-hermit/librocat` then `/plugin install librocat@librocat`. Codex `codex plugin marketplace add laughing-hermit/librocat` then `codex plugin add librocat@librocat`. Cursor, in its chat: `/add-plugin https://github.com/laughing-hermit/librocat`. GitHub Copilot, with the Copilot CLI: `copilot plugin install laughing-hermit/librocat:plugin`.
- Every agent at once, with your package manager. With Agent Plugins (https://agent-plugins.org): `npx plugins add laughing-hermit/librocat` (or `pnpm dlx`, `yarn dlx`, `bunx`) installs the plugin, skills included, in every agent that takes them.
- Without Agent Plugins, MCP (https://modelcontextprotocol.io) + Agent Skills (https://agentskills.io), for OpenCode, OpenClaw, Hermes, Windsurf, Gemini CLI, any other MCP agent, a second library, or a self-hosted librocat: `npx add-mcp https://librocat.com/mcp --name librocat -g` writes the MCP entry for every agent it finds, and `npx skills add laughing-hermit/librocat -g` installs the three skills. Without `-g`, both write the project's config instead (to commit for a team). `-a <agent>` picks agents, `-y` skips prompts; `pnpm dlx`, `yarn dlx`, and `bunx` work too. For a self-hosted librocat or a second library, swap the URL (quote a `?library=` URL in zsh).
- One agent at a time: Claude Code `claude mcp add --transport http librocat https://librocat.com/mcp`. Codex `codex mcp add librocat --url https://librocat.com/mcp`. Cursor `{ "mcpServers": { "librocat": { "url": "https://librocat.com/mcp" } } }`. GitHub Copilot, in VS Code's `.vscode/mcp.json`: `{ "servers": { "librocat": { "type": "http", "url": "https://librocat.com/mcp" } } }`. OpenClaw `openclaw mcp add librocat --url https://librocat.com/mcp --transport streamable-http --auth oauth`, then `openclaw mcp login librocat`. Hermes `hermes mcp add librocat --url https://librocat.com/mcp --auth oauth`. Antigravity, which doesn't read the skills from where `npx skills add` puts them, takes the plugin folder, the server and the skills together: `npx giget gh:laughing-hermit/librocat/plugin ~/.gemini/config/plugins/librocat --force`. Agents that only run stdio servers: `{ "mcpServers": { "librocat": { "command": "npx", "args": ["-y", "mcp-remote", "https://librocat.com/mcp"] } } }`.
- Skills alone, for agents with Agent Skills but not Agent Plugins: `npx skills add laughing-hermit/librocat`, plus the MCP line above. The skills call the MCP's tools.
- Desktop agents, the ones that work on your computer, install the plugin from this repository, which brings the skills and the MCP together. Claude Desktop and Cowork: Customize › Plugins › Add › Add marketplace, `laughing-hermit/librocat`; then install librocat and connect its connector on the plugin's Connectors tab. ChatGPT, in its desktop app: a Business or Enterprise admin imports `https://github.com/laughing-hermit/librocat` (Admin › Plugins › Add › Import marketplace), then members install librocat from Plugins; without an admin, the MCP without the skills goes in the desktop app's Settings › MCP servers › Add server, with `https://librocat.com/mcp`. Grok Bot installs Cursor's plugins: a Cursor Teams admin imports the repository as a team marketplace (Dashboard › Plugins & MCPs › Team Marketplaces › Add Marketplace › Import from Repo), then each member adds librocat from Connect apps in Grok Bot's sidebar; on your own, Cursor's marketplace once librocat is listed. A second library alongside the first, or a self-hosted librocat, takes its address as a custom connector or MCP server: the MCP without the skills.
- Works with any MCP client: first the four coding agents, Claude Code, Codex, Cursor, and GitHub Copilot; then OpenCode, OpenClaw, Hermes Agent, Windsurf, Gemini CLI, Antigravity, NemoClaw (remote HTTPS MCP only), and the desktop agents above.

## Self-host (free, Docker)

- `git clone https://github.com/laughing-hermit/librocat.git && cd librocat/self-host && ./setup.sh` runs the same site, dashboard, and MCP on your own server with Docker or Podman: no limits, no billing, community support (SELF_HOSTING.md). Agents connect the same way either way; self-hosting changes who runs the server and which model Libro uses: the same model librocat.com uses (with an API key), an open-source one on your own server, or none (SELF_HOSTING.md). Search needs no model. With a local model, or none, it runs offline, driven by a local agent such as opencode.
- Connect agents to it: `npx add-mcp https://your-host/mcp --name librocat -g` and `npx skills add laughing-hermit/librocat -g`. For Antigravity, copy the plugin folder with the `npx giget` command above, then set `serverUrl` in its `mcp_config.json` to your server's `/mcp`. The dashboard's Connect page shows these commands with your server's address.
- Move a library between librocat.com and a self-hosted librocat: Export, in the dashboard's Settings, on one (zips of the OKF files and the kept sources' text, then the attached files in parts of about a gigabyte), Import, in Settings, on the other (all the zips at once, any size), then the MCP + Skills commands with the new URL.

## What a librocat library does

- Attach documents and pictures, then catalog them. Files (PDFs, Word documents, spreadsheets, slides, text and code, pictures) are attached on the dashboard's Library › Files, or by an agent with a shell through `add_source` in two steps (`file` returns an `upload_url`; POST the bytes there with curl, then `add_source` with the `storage_id`, the filename, and a title). For a web page it can fetch, the agent sends the page's text with `location`; a PDF at a URL, it downloads, then uploads. librocat keeps the original and reads its text where code can (text, HTML, PDF, Word, spreadsheets, slides), so `search` finds it by its words and its title right away, after the concepts (`type: "Source"` hits); a picture or a scanned PDF is found by its title and by the concepts written about it. Then your agent reads it (`get_source`: the text, or the picture itself) and writes what matters as concepts that cite it (`source:<id>` in `sources`). The `ingest-document` skill shows how. librocat keeps text and pictures, the things agents read; it refuses audio and video, so keep a recording's transcript instead (a `.vtt` or `.srt` file, or its text). Storage: 100 MB on Free, 5 GB on Individual, and 25 GB shared by a Team's libraries, files and text together; one file is up to 50 MB on Free and 200 MB on a paid plan. An agent attaching a file spends none of Libro's credits. On paid plans, librocat fetches pages itself in two cases only: the reading list (save a link on the dashboard, or `add_source` with only a URL; it stays unread until a concept cites it), and source watch (Libro's weekly review fetches again the kept pages concepts cite, and puts those concepts up for review when a page changed). Public pages only.
- The library is the source of truth; export gives the same OKF files back. Every write is a revision (`get_concept` with `history: true`), attributed to the person and the agent that made it.
- Automatic cataloging fills a missing description or tags after `ingest`/`update`; each concept filled spends one of Libro's credits, the plan's monthly allowance. Libro's model, a small judgment model, picks from the concept's own sentences and the library's tags and composes no text of its own: what it can't pick stays blank for your agent. Libro also reads every file a person adds on the dashboard, and every link they save, end to end (a credit for about three pages; files use at most half of the month's credits), describes it, and flags the concepts it likely changes.
- Libro, the library cat (librocat's librarian): once a week (on Free, in the weeks something was written) Libro puts proposals in Needs you (a concept past its review date: still true, or retire; supersede a duplicate; retire a superseded or never-read concept; merge two spellings of a tag). After every review, Libro screens for pairs that say the same thing (same shelf, shared tags, overlapping titles) and for review dates. Apart from the description and tags it fills in, Libro only proposes: nothing in Needs you changes until you approve it. Your agent works the shelf with you (`review_shelf`; `propose` a merge with its draft, which Libro checks against both concepts; `decide` on your yes), or you decide on the dashboard. Every decision is a revision. `status` reports `review_shelf`.
- Search goes by words, and your agent drives it: it writes keyword searches and tries other words when the first ones miss. Words are stemmed, the query is expanded through the thesaurus (a synonym finds its preferred tag, a tag its narrower terms), and matches in a concept's title, description, and tags count twice.
- The ready-reference file: every `search` is filed as a question with what answered it. Asked again with the same words, the earlier answer comes first (`ready_reference: true` on the hit). Questions that found nothing are in Libro's report, emailed every Monday on paid plans and on the month's first Monday on Free: what to write down next.
- Review dates: give time-bound concepts `stale_after` (an ISO date) on `ingest`/`update`. Every summary carries `stale_after` and `stale`; `update` with `verify: true` records that you checked it (OKF `verified`).
- librocat refuses to store secrets (private keys, API keys in known formats). Record where a secret lives instead ("STRIPE_SECRET_KEY, in Doppler at prod/stripe").

## Tools

search, get_concept, list, graph, ingest, update, delete, files_changed, thesaurus, set_term, status, add_source, get_source, review_shelf, propose, decide: sixteen, the same on librocat.com and a self-hosted librocat. To catalog a code repository, the agent reads it and `ingest`s a concept per module or component, with `sources` naming its files. `search`/`list` take `shelf` (the leading directory of ids, e.g. `acme`): one library, many shelves; read your project's shelf first and the whole library second. `ingest` also takes `concepts: [...]` to write up to 100 in one call (one result per item), and a new concept may come back with `possible_duplicates` for the agent to judge. `ingest`/`update` take `status: draft | stable | deprecated`. `update` takes `superseded_by`, and `new_id` to move a concept and rewrite every link to it. `get_concept` returns a concept's `links` (outbound and inbound), its revisions with `history: true`, and one past revision with `revision`. `ingest`/`update` take `sources` (what a concept describes or came from: repository paths, code links, or a document's, page's, or video's URL), and `files_changed` (the files a commit touched) puts those concepts up for review; the agent calls it after a commit with the changed paths. `search`/`list` take `author`. Several libraries: `https://librocat.com/mcp` reaches your default library, `https://librocat.com/mcp?library=<slug>` another you belong to (one sign-in covers all); `status` names the library and lists the others. `thesaurus` reads the controlled vocabulary and `set_term` sets one tag's entry (writes normalize tags through it, search expands with it). `review_shelf` lists Libro's proposals and the CREW/MUSTIE weeding report (`weeding`). `list` with `format: "markdown"` renders one index.md shelf list per directory (the export zip includes them). `status` reports the type/tag vocabulary, link health, the plan, quota, Libro's credits this month (`index_credits`), review_shelf, and sources. Source copies: `add_source` keeps a document's, page's, or transcript's exact text (a file goes through the upload link instead, and librocat reads it), and a concept cites the copy in `sources` by its URL or `source:<id>`; `get_source` reads it back as passages for a `query` or a page at a time (`part`), and `get_concept` lists a concept's kept sources in `stored_sources`. New text for a kept URL puts the concepts citing it up for review. Search finds kept sources by their words and their titles; a library keeps up to 100 MB of files and text on Free and 5 GB on Individual, and a Team's libraries share 25 GB.

## Pricing

- Free: $0. 1 person, hosted MCP on every agent and machine, 1 library of 1,000 concepts, 100 MB of attached files and text (up to 10 MB of it text, 50 MB a file), 200 of Libro's credits a month (a credit catalogs one concept, or reads about three pages of a file you add), 60 calls a minute and 10,000 a month, 1,500 writes a month, 1 GB of file transfer a month (files downloaded or attached), Libro's review shelf (weekly while you write), Libro's report once a month, revision history. Plans are for librocat.com; self-hosting is free, with no limits.
- Individual is per library: each library carries its own plan. One Team covers every library its owner owns, up to 10, on one bill, and they share its limits.
- Individual: $12/mo, or $10/mo billed yearly ($120), per library. 1 person, 5,000 concepts, 5 GB of files and text (up to 250 MB of it text, 200 MB a file), 500 of Libro's credits a month, then $0.01 a credit if you turn on pay-as-you-go (off until you do; it stops at a monthly cap you set), 300 calls a minute and 30,000 a month (each counted by what it reads: once per 256 KB), 5,000 writes, and 10 GB of file transfer a month, Libro's review and report every week, the reading list and source watch.
- Team: $15 per person a month, or $12.50 billed yearly ($150 per person), 3 to 100 people (the seats change on the Billing page), each with their own sign-in (invite link) and a role: Admin, Editor, or Reader. One Team covers up to 10 libraries its owner owns, on one bill, and they share its limits: 15,000 concepts, 25 GB of files and text (up to 1 GB of it text, 200 MB a file), 2,500 of Libro's credits a month, then $0.01 a credit with pay-as-you-go, 600 calls a minute, 30,000 calls and 5,000 writes a month per person, 50 GB of file transfer a month, and the same weekly review and report, reading list, and source watch as Individual.
- Enterprise: custom limits, SSO, security review: support@librocat.com.
- Calls, writes, and file transfer refill day by day over 30 days, and `status` reports what's left (`monthly`); Libro's credits renew on the 1st of each month (UTC). History keeps each concept's last 100 revisions, and up to 2,000 in a library on Free, 10,000 on Individual, and 30,000 on Team. Prices are in US dollars; sales tax or VAT is added at checkout where it applies.
- When a paid plan ends, Individual or Team: the library goes back to Free with everything in it, and new concepts and files wait until it's under Free's limits. A Team's other members pause until it's on Team again. Free has one library, so 30 days later the owner's other libraries pause (agents can't reach them; the dashboard still opens, exports, or deletes them). Choosing a plan brings everything back. What's still over Free's limits after 12 months is deleted, after two emails.
- Export or delete everything, anytime. Cancel whenever. Your library stays yours.

## Docs

- Questions and answers: https://librocat.com/#faq
- Site: https://librocat.com (about: https://librocat.com/about, security: https://librocat.com/security)
- Code and docs: https://github.com/laughing-hermit/librocat (Apache-2.0: the skills, the dashboard, the MCP and its backend, the self-host bundle, and Libro)
- Standards: Agent Plugins (https://agent-plugins.org), Agent Skills (https://agentskills.io), MCP TypeScript SDK (https://github.com/modelcontextprotocol/typescript-sdk), OKF (https://github.com/GoogleCloudPlatform/open-knowledge-format)
- Contact: support@librocat.com
- Operator: Laughing Hermit, Inc. (librocat is a Laughing Hermit, Inc. product). The site is librocat.com; email comes from mail@librocat.com, and support is support@librocat.com.