Kairn

Kairn

Watch the 30-second tour on GitHub .

Context-aware knowledge engine for AI assistants.

Status: pre-1.0. In daily use since February 2026, with a test suite that runs on Linux, macOS and Windows (see Development) and a published LongMemEval-S benchmark (measured before 0.3.0). Interfaces may still change between releases until 1.0. Feedback and issues welcome.

Other tools give your AI a memory. Kairn gives it a knowledge graph with intelligent context routing. It knows what to load, when to load it, and how much - so your AI stays focused, not overwhelmed.

pip install kairn-ai

kairn init ~/brain kairn serve ~/brain

Claude Code and Codex each take one line; --init creates ~/brain and its database on first start, so this works even without kairn init:

claude mcp add kairn -- kairn serve --init ~/brain

codex mcp add kairn -- kairn serve --init ~/brain

Or install it as a one-click bundle, no Python setup required: download the .mcpb file from the latest release and open it with a bundle-aware app such as Claude Desktop.

For other clients, see Quick Start below. New to Kairn? Jump to First 5 Minutes.

Install routes

The bundle carries no Kairn source of its own. It declares kairn-ai as a dependency and the host resolves it with uv, so a bundle install and a pip install run identical code. Where the database lives is configurable when you install the bundle; it defaults to ~/.kairn and never leaves your machine.

Why Kairn?

Every AI conversation starts from scratch. Previous insights, decisions, and patterns - gone. Existing memory tools store flat key-value pairs that can't represent relationships or surface the *right* context at the *right* time.

Kairn is different:

• Context Router + Progressive Disclosure - Automatically loads relevant subgraphs based on keywords, starting with summaries and drilling into details only when needed. No other tool does this.
• Knowledge Graph with FTS5 - Not flat storage. Typed relationships (depends-on, resolves, causes) between nodes with provenance tracking and full-text search across everything.
• Experience Decay + Auto-Promotion - Experiences lose relevance over time (biological decay model). Frequently-accessed experiences auto-promote to permanent knowledge. Your AI naturally forgets what doesn't matter.
• 22 MCP Tools - Works with Claude Code, Codex, Claude Desktop, Cursor, VS Code, Windsurf, and any MCP client. Includes kn_judge for 5-verb relationship judgments and kn_doctor for read-only health diagnostics.
• Per-Workspace Isolation - Each workspace is its own isolated SQLite store. JWT auth and role-based access control (owner / maintainer / contributor / reader) ship for team deployments.

Quick Start

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows:

{

"mcpServers": { "kairn": { "command": "kairn", "args": ["serve", "--init", "~/brain"] } } }

Cursor

Add to .cursor/mcp.json:

{

"mcpServers": { "kairn": { "command": "kairn", "args": ["serve", "--init", "~/brain"] } } }

VS Code

Add to .vscode/mcp.json:

{

"servers": { "kairn": { "type": "stdio", "command": "kairn", "args": ["serve", "--init", "~/brain"] } } }

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{

"mcpServers": { "kairn": { "command": "kairn", "args": ["serve", "--init", "~/brain"] } } }

Restart your editor. Kairn's 22 tools appear in the MCP section.

First 5 Minutes

A guided first run, end to end:

pip install kairn-ai

kairn init ~/brain # creates the workspace + database (optional: serve --init does it on first start)

Add the one-liner from above (or your client's Quick Start snippet), then restart the client. Once connected, ask your assistant to remember something:

"Remember that we chose Postgres over SQLite for the analytics service because we needed concurrent writers."

That calls kn_learn under the hood and returns a JSON envelope like this (captured from a real run, via kairn learn, the CLI mirror of the tool):

{"_v": "1.0", "stored_as": "node", "node_id": "002d9c22", "experience_id": "d0710c2f", "type": "decision", "confidence": "high", "namespace": "knowledge", "candidates": []}

Start a new session and ask it to recall the same thing - that calls kn_recall and surfaces what you just stored, no re-explaining required:

{"_v": "1.0", "count": 2, "results": [

{"source": "node", "id": "002d9c22", "name": "Decision: we chose Postgres over SQLite for the analytics service beca", "type": "learned_decision", "namespace": "knowledge", "description": "we chose Postgres over SQLite for the analytics service because we needed concurrent writers", "relevance": 1e-06, "relevance_kind": "match"}, {"source": "experience", "id": "d0710c2f", "type": "decision", "namespace": "knowledge", "content": "we chose Postgres over SQLite for the analytics service because we needed concurrent writers", "confidence": "high", "relevance": 1e-06, "relevance_kind": "match_recency"} ]}

kn_learn stored both a permanent graph node and a decaying experience (high confidence does both, see Confidence routing); kn_recall found both from a three-word topic.

Read `relevance_kind` before you read `relevance`. match is lexical match strength (bm25). match_recency is match strength with a small recency nudge, a factor between 0.9 and 1.1, on an experience found by a text search. recency is pure time-decay on an experience listed with no search text: it says how old the row is, not whether it matched. similarity is embedding cosine on the semantic-recall path, and unscored marks a row the surface had no ranking for and filled in with a constant, from crossref or a text-less browse query. Both rows above show 1e-06 because SQLite's bm25 gives almost no weight to a word that appears in most entries. On a store with one fact every word does, so the score sits at SQLite's floor. It is not a bad match. After eight more unrelated facts, the same recall measured about 0.5 for both rows. On a store this small, a topic with a word the fact does not contain can score 0.0, and the row is still returned. Scores are only comparable within one result set and are not comparable across kinds, so do not sort a mixed result set on relevance alone. Same caution for min_relevance on kn_recall: it gates nodes on match strength and experiences on recency, one number against two scales. On a small store, a value such as 0.1 drops the node and keeps the experience (measured). On kn_memories and kn_prune, which see experiences only, it is recency - and on kn_prune it deletes.

Run kairn status ~/brain any time as a smoke test - if it prints a JSON stats block (nodes/edges/experiences counts), the workspace is healthy. For a scripted tour, kairn demo adds sample data (two nodes, one edge and two experiences, measured) to the workspace it is given, so give it a throwaway one: kairn init ~/kairn-tour && kairn demo ~/kairn-tour.

Which tool when

22 tools is a lot to hold in your head on day one. Most sessions only need these:

Everything else (kn_crossref, kn_related, kn_connect, kn_judge, kn_project/kn_projects/kn_log, kn_idea/kn_ideas, kn_promote_pending, kn_prune, kn_remove, kn_status, kn_doctor) is advanced usage - see the full 22 Tools reference below once you're past the basics.

22 Tools (kn_ prefix)

All tools follow MCP protocol with JSON responses.

Graph (6)

Project Memory (3)

Experience Memory (5)

Ideas (2)

Intelligence (5)

| `kn_