Kybase

Your agent remembers. You can read every word.

Kybase is a self-hosted knowledge base for AI agents. Your agent searches and writes Markdown notes over MCP; you read, edit and link the same notes in your browser.

Install Kybase View on GitHub

Free and open source under AGPL-3.0. Runs on your server or your laptop.

Your agent

Why didn't we add a message broker back then?

search_notes "message broker decision"

found ADR-001, 2 sections

We decided against it in ADR-001. A broker would be one more system to run, monitor and back up, and the queue fits in Postgres. The note also says to revisit this once the queue passes 1,000 jobs a minute.

Source ADR-001 Postgres as the primary datastore

ADR-001 Postgres as the primary datastore

Decision

Jobs, documents and embeddings live in one Postgres. A second datastore needs a new ADR.

Why no broker

A broker would be one more system to run, monitor and back up. The job queue fits in Postgres, and one database means one backup. See Event Bus Architecture.

Revisit when

The queue passes 1,000 jobs a minute, or a second team needs the events.

How it works

  1. Run it

    One Docker Compose stack on your server, or npx kybase-mcp on your laptop with nothing else to install.

  2. Connect your agent

    Add the address to Claude, ChatGPT or Cursor and sign in once in your browser. Each app gets its own token you can revoke.

  3. Work as usual

    The agent looks things up before it answers and writes down what it learns. You open the same notes, fix them and link them.

Connect your agent

Kybase speaks MCP at /api/mcp. Apps that support OAuth sign in once in your browser, so your secret never goes into their settings.

claude mcp add --transport http --scope user kybase https://your-domain/api/mcp

Then run /mcp in Claude Code, pick kybase, choose Authenticate and enter your KYBASE_SECRET on the page that opens.

What you get

Notes you can read
Everything the agent keeps is plain Markdown. Read it, correct it, search it, back it up.
One memory for every agent
Claude, ChatGPT, Cursor and the web app all work with the same notes.
Search by words and by meaning
An agent finds the right note whether or not it knows the exact wording.
Reads and writes by section
An agent opens the part of a long note it needs and adds to it without rewriting the rest.
Links and a graph
[[Wikilinks]] connect notes, and the graph shows each folder as its own island.
Every change kept
Each edit keeps the previous version, labelled with the app that made it, ready to restore.

Your notes stay with you

Kybase runs where you put it, on your server or your laptop. There is no Kybase account and no cloud service of ours in between.

With Ollama, notes and their embeddings never leave your machine. Google and OpenAI embeddings are there if you prefer them, and Settings says plainly that picking one sends note text to that provider.

  • Open source, AGPL-3.0
  • Export everything as Markdown in folders
  • Each connected app has its own revocable token

Install

The full app gives you the web interface, the graph, share links and one knowledge base for several agents. It needs Docker and about 1 GB.

macOS and Linux

git clone https://github.com/Kyrzin/kybase.git
cd kybase
cp .env.example .env
sed -i.bak "s/^KYBASE_SECRET=$/KYBASE_SECRET=$(openssl rand -hex 32)/" .env
sed -i.bak "s/^POSTGRES_PASSWORD=$/POSTGRES_PASSWORD=$(openssl rand -hex 16)/" .env
rm -f .env.bak
docker compose pull && docker compose up -d

Windows commands are in the README.

Then

Open http://localhost:3000 and sign in with the KYBASE_SECRET from .env.

For search by meaning, pick an embedding provider in Settings: Ollama on your machine, or Google or OpenAI with an API key.

Then connect your agent.