kybase

Kybase is a self-hosted persistent memory knowledge base for AI agents, with the core idea that "humans use Markdown, agents use MCP." It solves the problem of agents forgetting context after a session ends, allowing knowledge to exist independently of agents, be shared by multiple agents, and be edited manually.

Main capabilities

• Long-term memory: Provides cross-session, cross-tool long-term memory for MCP-capable agents such as Claude, Cursor, and Windsurf.
• Markdown knowledge base: All notes are plain-text Markdown, readable, editable, greppable, and backup-able with cp.
• Hybrid search: Full-text search and semantic-based search are merged into a single ranked result, so agents can find notes whether or not they know the exact wording.
• Section-level read/write: Agents can read or edit only the needed parts of a note instead of the entire file.
• Bidirectional links and knowledge graph: Automatically connects related notes via [[wikilinks]] to form a knowledge graph.
• MCP tools: Provides 18 MCP tools via Streamable HTTP at /api/mcp; OAuth-capable clients can log in through the browser to obtain an independent token.
• Web UI: Provides a browser interface, graph view, and share links, and supports multiple agents connecting to the same knowledge base at the same time.
• Export and import: In settings, you can export a .zip (pure Markdown, with folders as directories, readable by editors such as Obsidian), and you can also import a .zip to merge it back into the knowledge base.
• Public sharing: A single note can generate a public read-only link that renders Markdown, requires no login, and displays wikilinks as plain text to prevent leaking the entire vault; it can be revoked in settings.
• Backup and upgrade: All data is stored in a single Postgres volume, supports pg_dump backups, and migrations are automatically applied on startup.

Usage

Quick start

• Local agents only (no Docker, no database): Put the corresponding MCP configuration into the client and restart; notes are stored in ~/.kybase, and you can use kybase-mcp export vault.zip to export them as pure Markdown.
• Full functionality (Web UI, graph, sharing, multi-agent): macOS/Linux and Windows (PowerShell) each have corresponding startup commands, which generate the required keys and start the service. Installation is about 1 GB, including the application and database. After startup, open http://localhost:3000，用 KYBASE_SECRET login (can be viewed via grep KYBASE_SECRET .env or PowerShell's Select-String KYBASE_SECRET .env), then connect the agent.

Semantic search

An embedding provider is required; select one in settings:

• Google or OpenAI: just paste the API key.
• Ollama (local): after starting it once, select the model in settings; the command is docker compose --profile ollama up -d. Because the image includes NVIDIA and AMD GPU runtimes (about 4 GB), it is not installed by default.

Connecting agents

Kybase provides a Streamable HTTP MCP service at /api/mcp. Clients that support OAuth can log in once via the browser and obtain an independent token (listed in Settings → Access and revocable individually), with no need to put KYBASE_SECRET in the configuration.

• Claude Code: add it once and it works for all projects, then run /mcp, select kybase → Authenticate, and enter KYBASE_SECRET on the page that opens.
• Claude Desktop and claude.ai: Custom → Connectors → Add custom connector, enter the same URL, then connect and log in. The instance must be reachable from the internet over HTTPS; in Claude Desktop, remote server configuration does not go in claude_desktop_config.json.
• Cursor: configure in ~/.cursor/mcp.json (global) or .cursor/mcp.json (project), then connect kybase under Custom → MCPs and log in.
• Windsurf: configure in ~/.codeium/windsurf/mcp_config.json, using serverUrl instead of url.
• Clients that only support stdio: use the npx -y kybase-mcp configuration from Quick Start. Note: a request header containing KYBASE_SECRET has full access to the entire instancepermissions, is only for clients without OAuth, and should be kept in your own configuration and never committed to a repository.

How agents use it

• Search indicates the matching note section, not just the note, saving the read cost of subsequent steps, and the same applies when writing back.
• The server includes instructions that teach the agent to search before writing and to add [[wikilinks]] to related notes, so the graph grows with the work instead of filling up with orphan nodes.

Use cases

• Individuals or teams who want AI agents to remember long-term context such as project decisions, environment configuration, and technical approaches.
• Multiple agents (Claude, Cursor, Windsurf, and the Web UI) sharing the same knowledge base.
• Knowledge management that needs to be private, self-hosted, and fully owned by you.
• Wanting notes and agent memory to become one, so you can manually correct what the agent got wrong.

Limitations and notes

• You need to deploy and maintain it yourself (Docker installation is about 1 GB, local Ollama about 4 GB).
• Private by default, with no SaaS account, no external memory service, and no cloud database.
• Cloud embedding providers are optional: choosing Google or OpenAI sends the full text of notes to that provider to compute embeddings; Ollama keeps everything local.
• Licensed under AGPL-3.0, free to use, modify, and self-host; if you run a modified version as a network service, you must provide the source code to users under the same license. Commercial licensing (such as embedding it in a closed-source product or service) requires contacting the author.
• More documentation: SECURITY.md (threat model), CONTRIBUTING.md (running locally, submitting PRs), docs/backup.md, docs/upgrading.md, packages/kybase-mcp (standalone stdio package).