kairn

# Kairn


![kairn](https://raw.githubusercontent.com/primeline-ai/kairn/main/assets/hero.png)

> Context-aware knowledge engine for AI assistants.

<!-- mcp-name: io.github.primeline-ai/kairn -->

**Status: Alpha.** The API and CLI are functional and tested (see
[Development](#development)), but interfaces may still change between
releases. 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.

```bash
pip install kairn-ai
kairn init ~/brain
kairn serve ~/brain
```

Add it to Claude Code in one line:

```bash
claude mcp add kairn -- kairn serve ~/brain
```

Or install it as a one-click bundle, no Python setup required: download the
`.mcpb` file from the [latest release](https://github.com/primeline-ai/kairn/releases/latest)
and open it with a bundle-aware app such as Claude Desktop.

For other clients, see [Quick Start](#quick-start) below. New to Kairn? Jump to [First 5 Minutes](#first-5-minutes).

## Install routes

| Route | Who it is for | Command |
|---|---|---|
| PyPI | anyone with Python, and every MCP client | `pip install kairn-ai` |
| MCP Bundle (`.mcpb`) | Claude Desktop and other bundle-aware apps; no Python install needed | download from [Releases](https://github.com/primeline-ai/kairn/releases) and open it |
| Claude Code | one line, uses the PyPI install | `claude mcp add kairn -- kairn serve ~/brain` |

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 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`:

```json
{
  "mcpServers": {
    "kairn": {
      "command": "kairn",
      "args": ["serve", "~/brain"]
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "kairn": {
      "command": "kairn",
      "args": ["serve", "~/brain"],
      "env": {
        "KAIRN_LOG_LEVEL": "WARNING"
      }
    }
  }
}
```

### VS Code

Add to `.vscode/mcp.json`:

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

### Windsurf

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

```json
{
  "mcpServers": {
    "kairn": {
      "command": "kairn",
      "args": ["serve", "~/brain"]
    }
  }
}
```

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

## First 5 Minutes

A guided first run, end to end:

```bash
pip install kairn-ai
kairn init ~/brain              # creates the workspace + database
```

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):

```json
{"_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:

```json
{"_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", "description": "we chose Postgres over SQLite for the analytics service because we needed concurrent writers", "relevance": 1.0},
  {"source": "experience", "id": "d0710c2f", "type": "decision", "content": "we chose Postgres over SQLite for the analytics service because we needed concurrent writers", "confidence": "high", "relevance": 1.0}
]}
```

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

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. Want a scripted tour of every core feature instead of doing it by hand? Run `kairn demo ~/brain` - it walks through node creation, querying, experience saving, learning, recall, and context in about 30 seconds.

### Which tool when

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

| You want to... | Use | Why |
|---|---|---|
| Remember something new (a decision, gotcha, pattern, solution) | `kn_learn` | Default entry point - auto-routes to a permanent node (high confidence) or a decaying experience (medium/low), no need to decide yourself |
| Capture a stated user preference the moment it is expressed | `kn_preference` | Dedicated preference write path - you (the calling model) state the preference as one explicit sentence; stored with the longest half-life of any type |
| Add a permanent named concept you already know is durable | `kn_add` | Skips decay entirely - for structural knowledge, not day-to-day experience |
| Log a one-off experience with explicit confidence/decay control | `kn_save` | Lower-level primitive `kn_learn` wraps - reach for it when you want to set confidence/decay yourself |
| Search the permanent knowledge graph by text, type, tags, or namespace | `kn_query` | You're looking for nodes, not decaying experiences |
| Search saved experiences, ranked by relevance and decay | `kn_memories` | You're looking for experience content (solutions, gotchas, workarounds), not graph nodes |
| Surface everything relevant to a topic in one call | `kn_recall` (flat list) or `kn_context` (subgraph, progressive disclosure: summary first, full detail on demand) | You don't know yet whether the answer is a node or an experience - let Kairn search both |

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](#22-tools-kn_-prefix) reference below once you're past the basics.

## 22 Tools (kn_ prefix)

All tools follow MCP protocol with JSON responses.

### Graph (6)

| Tool | Description |
|------|-------------|
| `kn_add` | Add node to knowledge graph |
| `kn_connect` | Create typed edge between nodes (lax-mode vocabulary) |
| `kn_judge` | Record 5-verb judgment edge (strict mode: `conflicts_with` / `supersedes` / `compatible` / `scoped` / `related`) |
| `kn_query` | Search by text, type, tags, namespace |
| `kn_remove` | Soft-delete node or edge (undo-safe) |
| `kn_status` | Graph stats, health, system overview |

### Project Memory (3)

| Tool | Description |
|------|-------------|
| `kn_project` | Create or update project |
| `kn_projects` | List projects, switch active |
| `kn_log` | Log progress or failure entry |

### Experience Memory (5)

| Tool | Description |
|------|-------------|
| `kn_save` | Save experience with decay |
| `kn_preference` | Capture a stated user preference at utterance time (longest half-life) |
| `kn_memories` | Decay-aware experience search |
| `kn_prune` | Remove expired experiences |
| `kn_promote_pending` | Promote high-access experiences to permanent nodes |

### Ideas (2)

| Tool | Description |
|------|-------------|
| `kn_idea` | Create or update idea |
| `kn_ideas` | List/filter ideas by status, category |

### Intelligence (5)

| Tool | Description |
|------|-------------|
| `kn_learn` | Store knowledge with confidence routing |
| `kn_recall` | Surface relevant past knowledge |
| `kn_crossref` | Find similar past solutions in the current workspace |
| `kn_context` | Keywords → relevant subgraph with progressive disclosure |
| `kn_related` | Graph traversal (BFS) to find connected nodes |

### Diagnostic (1)

| Tool | Description |
|------|-------------|
| `kn_doctor` | Read-only health checks (lock mode, FTS5 parity, promotion backlog, namespace sprawl, orphan edges) - returns structured envelope with per-check verdicts and roll-up summary |

## Resources & Prompts

**Resources** (read-only context for MCP clients):
- `kn://status` - Graph overview, active project
- `kn://projects` - All projects with recent progress
- `kn://memories` - Recent high-relevance experiences

**Prompts** (sessi