llm-kosh

Give your local LLMs a permanent, air-gapped memory cartridge.

llm-kosh is a lightning-fast, SQLite-backed memory system that gives AI assistants (like Claude and Cursor) permanent recall across sessions. Stop copy-pasting the same 15 architectural decisions and database schemas into every new chat.

By running completely locally, it guarantees zero cloud syncing, zero API costs, and absolute privacy for your proprietary codebase.

🚀 The Killer Feature: Native MCP Server

llm-kosh natively supports the Model Context Protocol (MCP). This means tools like Claude Desktop and Cursor can automatically search and read your memory cartridge without you doing anything.

Claude Desktop Setup

Simply add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "llm-kosh": {
      "command": "uvx",
      "args": ["llm-kosh", "mcp", "--root", "C:/path/to/your/cartridge", "--allow-write"]
    }
  }
}

Now, when you ask Claude "What database are we using for auth?", it automatically searches your llm-kosh cartridge and knows the answer.

🧠 Temporal Causal Reasoning Engine

Most memory systems do keyword retrieval. You get back five disconnected facts and have to assemble the story yourself.

llm-kosh includes a Temporal Causal Reasoning Engine that understands why things happened and in what order. When you ask about the authentication system, it doesn't just find five matching notes — it traces the causal chain: the decision that led to the refactor, the refactor that introduced the bug, the hotfix that closed the incident. In order. With confidence scores.

Before (keyword retrieval)

You: "What happened to the auth system last quarter?"

Results:
• [NOTE] JWT token refresh bug — Dec 14
• [DECISION] Migrate to OAuth2 — Oct 3
• [NOTE] Hotfix deployed — Dec 15
• [DECISION] Auth service staging deploy — Nov 8
• [NOTE] OAuth2 provider integration — Oct 22

Five facts. No order. No story. You assemble it manually.

After (causal reasoning)

You: "What happened to the auth system last quarter?"

Causal chain (stability: 0.85, 5 hops):
  1. Oct 3  → DECISION: Migrate to OAuth2 [approved by steering]
  2. Oct 22 → OAuth2 provider integration completed (ENABLES →)
  3. Nov 8  → Auth service deployed to staging, smoke tests passed (ENABLES →)
  4. Dec 14 → Token refresh bug discovered in production (CAUSES →)
  5. Dec 15 → Hotfix merged. Authentication fully stable. (SUPERSEDES Dec 14)

One coherent narrative. Cause and effect. Time-ordered. No assembly required.

How it works

The engine builds a causal graph over your memories as you add them. Each fact connects to related facts via typed edges (ENABLES, CAUSES, CONTRADICTS, SUPERSEDES, INFERS). When you query, it runs:

1. DCT resonance retrieval — finds facts that vibrate at the same frequency as your query
2. Bidirectional fiber bundle traversal — traces causal paths forward and backward through time
3. Lyapunov stability scoring — measures how coherent and non-contradictory the retrieved chain is
4. Escape mechanism — if the chain is unstable, surfaces contradictions and alternative routes

Benchmarked at 100% accuracy on temporal reasoning tests (10/10), up from a 50% baseline with keyword-only retrieval.

Try it via MCP (Claude Desktop)

Once the MCP server is running, Claude can call the reasoning engine directly:

You: "Walk me through what happened to our authentication system"

Claude uses: reasoning_query("authentication system history")
→ Returns causal narrative with timestamps, edge types, and stability score

Try it via Python

from llm_kosh.engine.reasoning import ReasoningEngine
from pathlib import Path

engine = ReasoningEngine(Path("./my-cartridge"))

result = engine.query(
    "What led to the auth system refactor?",
    temporal_context="2025-12-01T00:00:00Z",
    depth=5
)

# result.bundle.fibers — causal chain, time-ordered
# result.stability.score — how coherent the chain is (0–1)
# result.escape_triggered — True if contradictions were surfaced
for fact_id, fiber in result.bundle.fibers.items():
    print(f"{fiber.fact.valid_from}: {fiber.fact.content}")

✨ Features

• 🧩 Temporal Causal Reasoning: Understands why and in what order. Traces causal chains across your memory graph. 100% accuracy on temporal benchmarks.
• 🧠 Lightning Fast Local Memory: Powered by an embedded SQLite FTS5 database. Sub-50ms search times across thousands of context files.
• ⚡ Global Quick Capture: Press Ctrl+Shift+Space anywhere on your OS to instantly dump a thought, decision, or code snippet into your cartridge.
• 🛡️ Air-Gapped & Secure: Built-in safety Airlock prevents destructive writes. No data ever leaves your machine unless you explicitly pack it.
• 🖥️ Beautiful Desktop UI: Comes with a glassmorphism Electron/React desktop app to manage your memory, monitor the MCP daemon, and configure hotkeys.

📦 Quickstart

Get from zero to a running memory cartridge in under 2 minutes.

1. Install the core system

# Core memory store (no extra deps)
pip install llm-kosh

# With MCP server + FastAPI (recommended for Claude Desktop integration)
pip install "llm-kosh[server]"

# Everything including vector search
pip install "llm-kosh[all]"

2. Initialize a new cartridge

# Creates a new .llm-kosh root in your current directory
llm-kosh init --owner "Your Name"

3. Launch the Desktop App & Daemon

# Starts the UI, the background watcher, and the MCP bridge
llm-kosh desktop

📚 Deep Dives:

• Architecture Overview
• MCP Integration Guide
• Comprehensive CLI Reference
• Temporal Causal Reasoning Engine