Kairn

Kontextbewusste Wissens-Engine für KI-Assistenten.

Status: Alpha. Die API und die CLI sind funktionsfähig und getestet (siehe Entwicklung), aber die Schnittstellen können sich zwischen den Versionen noch ändern. Feedback und Issues sind willkommen.

Andere Tools geben Ihrer KI ein Gedächtnis. Kairn gibt ihr einen Wissensgraphen mit intelligentem Kontext-Routing. Es weiß, was es laden soll, wann es es laden soll und wie viel – damit Ihre KI fokussiert bleibt und nicht überfordert wird.

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

Fügen Sie es in einer Zeile zu Claude Code hinzu:

claude mcp add kairn -- kairn serve ~/brain

Oder installieren Sie es als Ein-Klick-Bundle, ohne Python-Einrichtung: Laden Sie die .mcpb-Datei aus der neuesten Version herunter und öffnen Sie sie mit einer Bundle-fähigen App wie Claude Desktop.

Für andere Clients siehe Schnellstart unten. Neu bei Kairn? Springen Sie zu Erste 5 Minuten.

Installationswege

Das Bundle enthält keinen eigenen Kairn-Quellcode. Es deklariert kairn-ai als Abhängigkeit und der Host löst sie mit uv auf, sodass eine Bundle-Installation und eine pip install identischen Code ausführen. Wo die Datenbank gespeichert wird, ist bei der Installation des Bundles konfigurierbar; standardmäßig liegt sie in ~/.kairn und verlässt nie Ihren Rechner.

Related MCP server: Mnemosyne

Warum Kairn?

Jede KI-Konversation beginnt bei null. Frühere Erkenntnisse, Entscheidungen und Muster – weg. Bestehende Gedächtnis-Tools speichern flache Schlüssel-Wert-Paare, die keine Beziehungen darstellen oder den richtigen Kontext zur richtigen Zeit anzeigen können.

Kairn ist anders:

• Kontext-Router + Progressive Disclosure – Lädt automatisch relevante Teilgraphen basierend auf Schlüsselwörtern, beginnt mit Zusammenfassungen und geht nur bei Bedarf ins Detail. Kein anderes Tool macht das.

• Wissensgraph mit FTS5 – Keine flache Speicherung. Typisierte Beziehungen (depends-on, resolves, causes) zwischen Knoten mit Herkunftsverfolgung und Volltextsuche über alles.

• Erfahrungsabfall + Auto-Promotion – Erfahrungen verlieren im Laufe der Zeit an Relevanz (biologisches Abklingmodell). Häufig abgerufene Erfahrungen werden automatisch zu permanentem Wissen befördert. Ihre KI vergisst natürlich, was nicht wichtig ist.

• 22 MCP-Tools – Funktioniert mit Claude Desktop, Cursor, VS Code, Windsurf und jedem MCP-Client. Enthält kn_judge für 5-Verb-Beziehungsurteile und kn_doctor für schreibgeschützte Gesundheitsdiagnosen.

• Pro-Workspace-Isolation – Jeder Workspace ist ein eigener isolierter SQLite-Speicher. JWT-Authentifizierung und rollenbasierte Zugriffskontrolle (Owner / Maintainer / Contributor / Reader) sind für Team-Bereitstellungen enthalten.

Schnellstart

Claude Desktop

Fügen Sie zu ~/Library/Application Support/Claude/claude_desktop_config.json hinzu:

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

Cursor

Fügen Sie zu .cursor/mcp.json hinzu:

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

VS Code

Fügen Sie zu .vscode/mcp.json hinzu:

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

Windsurf

Fügen Sie zu ~/.codeium/windsurf/mcp_config.json hinzu:

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

Starten Sie Ihren Editor neu. Kairns 22 Tools erscheinen im MCP-Bereich.

Erste 5 Minuten

Ein geführter erster Durchlauf, Ende zu Ende:

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

Fügen Sie den Einzeiler von oben (oder das Schnellstart-Snippet Ihres Clients) hinzu und starten Sie dann den Client neu. Sobald die Verbindung steht, bitten Sie Ihren Assistenten, sich etwas zu merken:

„Denken Sie daran, dass wir Postgres gegenüber SQLite für den Analysedienst gewählt haben, weil wir gleichzeitige Schreiber benötigten."

Das ruft intern kn_learn auf und gibt einen JSON-Envelope wie diesen zurück (aufgezeichnet von einem echten Lauf, über kairn learn, das CLI-Pendant des Tools):

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

Starten Sie eine neue Sitzung und bitten Sie sie, sich an dasselbe zu erinnern – das ruft kn_recall auf und zeigt, was Sie gerade gespeichert haben, ohne erneutes Erklären:

{"_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 speicherte sowohl einen permanenten Graphknoten als auch eine abklingende Erfahrung (hohe Konfidenz macht beides, siehe Konfidenz-Routing); kn_recall fand beide aus einem Drei-Wort-Thema.

Führen Sie jederzeit kairn status ~/brain als Smoke-Test aus – wenn es einen JSON-Statistikblock (Knoten/Kanten/Erfahrungszahlen) ausgibt, ist der Workspace gesund. Möchten Sie stattdessen eine skriptgeführte Tour durch alle Kernfunktionen, anstatt es manuell zu tun? Führen Sie kairn demo ~/brain aus – es führt Sie in etwa 30 Sekunden durch Knotenerstellung, Abfragen, Erfahrungsspeicherung, Lernen, Abrufen und Kontext.

Welches Tool wann

22 Tools sind am ersten Tag viel, um sie im Kopf zu behalten. Die meisten Sitzungen benötigen nur diese:

Alles andere (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) ist fortgeschrittene Nutzung – siehe die vollständige Referenz 22 Tools unten, sobald Sie über die Grundlagen hinaus sind.

22 Tools (kn_-Präfix)

Alle Tools folgen dem MCP-Protokoll mit JSON-Antworten.

Graph (6)

Projektgedächtnis (3)

Erfahrungsgedächtnis (5)

Ideen (2)

Intelligenz (5)

Diagnose (1)

Ressourcen & Prompts

Ressourcen (schreibgeschützter Kontext für MCP-Clients):

• kn://status – Graphenübersicht, aktives Projekt

• kn://projects – Alle Projekte mit aktuellem Fortschritt

• kn://memories – Aktuelle Erlebnisse mit hoher Relevanz

Prompts (Sitzungsverwaltung):

• kn_bootup – Aktives Projekt, aktuellen Fortschritt und Top-Erinnerungen laden (Sitzungsstart)

• kn_review – Sitzung zusammenfassen und nächste Schritte vorschlagen (Sitzungsende)

So funktioniert es

Architektur

Any MCP Client (Claude, Cursor, VS Code)
        │
        ▼ MCP Protocol (stdio)
FastMCP Server (22 tools)
        │
   ┌────┼────┐
   ▼    ▼    ▼
Graph  Memory  Intelligence
Engine Engine  Layer
   │    │      │
   └────┼──────┘
        ▼
   SQLite + FTS5
   (per-workspace)

Abklingmodell

Erlebnisse nehmen exponentiell an Relevanz ab:

relevance(t) = initial_score × e^(-decay_rate × days)

Die Halbwertszeiten werden anhand des realen Zugriffsschwanzes eines Produktions-Erlebnisspeichers kalibriert, nicht geraten (eine Ausnahme: preference ist ein neuer Typ ohne Zugriffshistorie, daher ist sein Wert eine dokumentierte Ersteinschätzung, bis echte Daten vorliegen).

Konfidenz-Routing über kn_learn:

• high → Permanenter Knoten + Erlebnis (kein Abklingen)

• medium → Erlebnis mit 2× Abklingen

• low → Erlebnis mit 4× Abklingen

• Automatische Hochstufung: 5+ Zugriffe → permanenter Knoten

• Knotenzugriffsverfolgung: kn_recall, kn_context und kn_crossref protokollieren, auf welche Knoten zugegriffen wurde, und speisen die Abkling- und Hochstufungspipeline

Benchmarks

Kairn erreicht 56,2 % gesamt bei LongMemEval-S (500/500 Fragen bewertet, GPT-4o-Reader + Judge, einzelner Lauf, 0 Fehler). Dies sind die realen Zahlen pro Kategorie, einschließlich der schlechten – jede rote Zelle verlinkt auf ihre Diagnose:

Die 500 Fragen umfassen 30 Enthaltungsvarianten (die richtige Antwort ist, abzulehnen); sie sind innerhalb ihrer Kategorien oben enthalten und werden separat bewertet: Kairn lehnt bei 96,7 % von ihnen korrekt ab.

Die Abruflatenz beträgt ~1,4 ms pro Abfrage (FTS5, prozessintern, ohne Netzwerk). Protokoll, Ehrlichkeitshinweise und Reproduktionsschritte: BENCHMARKS.md.

Diese Ergebnistafel bleibt aktuell: Jede Veröffentlichung, die den Abruf betrifft, veröffentlicht diese Zahlen neu, und eine schwache Zelle bleibt auf der Tafel, bis sich die Zahl tatsächlich ändert. Keine ausgewählten Läufe, keine versteckten Kategorien.

CLI

kairn init <path>              # Initialize workspace
kairn serve <path>             # Start MCP server (stdio)
kairn status <path>            # Graph stats
kairn demo <path>              # Interactive tutorial
kairn benchmark <path>         # Local performance benchmarks (latency, not LongMemEval)
kairn token-audit <path>       # Audit tool token usage
kairn import git <path> <repo>...  # Import git commit history (zero-LLM, offline)
kairn import claude-code <path>    # Import Claude Code session history (zero-LLM, offline)

Importieren deines Verlaufs

kairn import git <workspace> <repo>... befüllt einen Kairn-Speicher aus einem oder mehreren lokalen Git-Repositories zum Preis von $0 – keine LLM-Aufrufe, keine Netzwerkaufrufe. Conventional-Commit- Präfixe werden Erlebnistypen zugeordnet (fix: -> solution, feat:/refactor:/perf: -> pattern, alles andere -> decision); Merge-Commits werden übersprungen. Importierte Erlebnisse landen in einem eigenen imported-git-Namespace, getrennt von deinem organischen Wissen, sodass sie immer unterscheidbar sind und ein schlechter Import vollständig rückgängig gemacht werden kann.

kairn import git ~/brain ~/code/my-project --dry-run   # Preview first
kairn import git ~/brain ~/code/my-project              # Then import for real
kairn import git ~/brain ~/code/proj-a ~/code/proj-b --since 2026-01-01

Idempotent – ein erneuter Lauf importiert nur Commits, die noch nicht importiert wurden, sodass es sicher ist, erneut ausgeführt zu werden, wenn die Historie eines Repositories wächst.

Claude-Code-Transkripte

kairn import claude-code <workspace> befüllt deinen Kairn-Speicher aus deiner vorhandenen Claude-Code-Sitzungshistorie, ebenfalls zum Preis von $0 und vollständig offline. Ohne --root scannt es ~/.claude/projects (und ~/.claude-secondary/projects, falls du ein zweites Konto hast); --root PATH ist eine wiederholbare Überschreibung. Importierte Erlebnisse landen in ihrem eigenen imported-claude-code-Namespace, sodass sie von deinem organischen Wissen getrennt bleiben und ein schlechter Import rückgängig gemacht werden kann.

kairn import claude-code ~/brain --dry-run              # Review exactly what would be stored
kairn import claude-code ~/brain                        # Import (prompts once before writing)
kairn import claude-code ~/brain --root ~/other/projects --since 2026-01-01 --yes

Was gespeichert wird (grober Modus): ein Erlebnis pro Sitzung – der Titel der Sitzung plus dein erster Prompt dieser Sitzung. Dies ist bewusst eine detaillarme, präzise Zusammenfassung und keine feingranulare Extraktion einzelner Entscheidungen: Ein regelbasierter Extraktor ohne LLM kann eine erfasste Entscheidung nicht zuverlässig von gewöhnlichem Planungsgeplauder unterscheiden, daher importiert import claude-code einen sauberen Zeiger auf Sitzungsebene statt verrauschter Fragmente. Es ist kein vollständiges Transkriptarchiv und keine einmalige Migration – es ist idempotent und soll erneut ausgeführt werden, wenn deine Historie wächst.

Datenschutz. Jede gespeicherte Zeichenkette wird zuerst durch einen deterministischen Geheimnis-Redaktor geleitet (API-Schlüssel, Authorization/Bearer-Header, password=/token=/secret=-Zuweisungen, gängige Anbieter-Schlüsselformen, Private-Key-Blöcke, in URLs eingebettete Anmeldedaten). Tool-Ausgaben und Tool-Aufrufblöcke werden nie gelesen, nur dein eigener Prompt-Text. Der Redaktor ist Verteidigung in der Tiefe, nicht die einzige Kontrolle: Ein echter (nicht-Trockenlauf-)Lauf ist hinter einer expliziten Bestätigung gesperrt, und --dry-run zeigt dir den exakten Text nach der Redaktion, bevor etwas geschrieben wird. Die Redaktion ist durch ihre Regelsätze begrenzt, daher wird eine --dry-run-Überprüfung vor einem ersten echten Import empfohlen; nichts verlässt jemals deinen Rechner.

Konfiguration

KAIRN_LOG_LEVEL=INFO|DEBUG|WARNING    # Default: WARNING
KAIRN_DB_PATH=~/brain/.kairn         # Default: {workspace}/.kairn
KAIRN_CACHE_SIZE=100                  # LRU cache entries
KAIRN_JWT_SECRET=<your-secret>        # Required for team features

Entwicklung

git clone https://github.com/primeline-ai/kairn
cd kairn
pip install -e ".[dev,team]"
pytest tests/ -v --cov
ruff check src/ && ruff format src/

Projektstruktur

src/kairn/
├── server.py              # FastMCP server + 22 tools
├── cli.py                 # CLI commands
├── config.py              # Configuration
├── core/
│   ├── graph.py           # GraphEngine (6 tools)
│   ├── memory.py          # ProjectMemory (3 tools)
│   ├── experience.py      # ExperienceEngine (4 tools)
│   ├── ideas.py           # IdeaEngine (2 tools)
│   ├── intelligence.py    # IntelligenceLayer (5 tools)
│   └── router.py          # ContextRouter
├── storage/
│   ├── base.py            # Storage interface
│   └── sqlite_store.py    # SQLite + FTS5 implementation
├── models/                # Data models
├── events/                # Event bus
└── auth/                  # JWT + RBAC (team feature)

Leistung

Typische Betriebszeiten auf moderner Hardware:

Verwendet von

Lizenz

MIT

Teil des PrimeLine-Ökosystems

@PrimeLineAI · primeline.cc · Kostenloser Leitfaden