kilonova-mcp

Kilonova MCP

Persistent knowledge base tools for Claude Code.
Claude remembers your projects, decisions, and patterns across sessions — stored on your machine, no cloud required.

Built by AIM Studio · Free · MIT License

The Problem

Every Claude Code session starts cold. You re-explain your project structure, re-describe decisions you made last week, re-state what's in flight. Context burns fast.

The Solution: DOT + KB

Kilonova gives Claude a persistent knowledge base on your local machine. At session start, Claude loads your DOT (Document of Truth) — a compressed, structured reference doc with your project state, active tasks, decisions, and patterns. During the session, Claude writes new discoveries back to the KB. Next session, it's all there.

Session 1: Claude learns your architecture → kb_write saves the decision
Session 2: dot_load → Claude already knows. No recap needed.

Install

pip install kilonova-mcp

Or from source:

git clone https://github.com/MilnaOS/kilonova-mcp
cd kilonova-mcp
pip install -e .

Wire Up Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "kilonova": {
      "command": "python",
      "args": ["-m", "kilonova_mcp"],
      "env": {
        "KILONOVA_KB_ROOT": "/path/to/your/kb"
      }
    }
  }
}

Copy CLAUDE.md.template to ~/.claude/CLAUDE.md (or append to your existing one).

Quick Start

1. Create your first KB topic:

In Claude Code, just start writing:

mcp__kilonova__kb_write(
  topic="claude_context",
  entity_type="project_state",
  name="my-project",
  data={
    "name": "my-project",
    "status": "active",
    "location": "/path/to/project",
    "summary": "What this project is",
    "next_action": "What to do next"
  }
)

2. Load it next session:

mcp__kilonova__dot_load(topic="claude_context")

3. Search it:

mcp__kilonova__kb_search(topic="claude_context", query="authentication decision")

The DOT Format

A DOT is a plain text file with three sections:

---SYMBOLS---
[PR]=My Project (/path/to/project)
[DB]=Database (PostgreSQL on localhost:5432)

---TOC---
1:Projects|1.1:My_Project
2:Active_Tasks
3:Decisions

---CARDS---

## [1] PROJECTS
### [1.1] My Project
STATUS: active
NEXT: wire up the auth flow

Symbols compress repeated references. The TOC lets Claude fetch only the section it needs. Cards hold the actual content.

See example_dot/ for a starter template.

Starter Schema: claude_context

Copy schemas/claude_context/ into your KB directory under <kb_root>/claude_context/schemas/:

Entity type	Use for
project_state	Current status, location, next action per project
decision	Architectural choices with rationale
pattern	Code conventions, gotchas, file locations
active_task	In-flight work across sessions
session_note	End-of-session summaries

Tools

Tool	Description
dot_load(topic)	Load full DOT document into context
kb_search(topic, query)	Search records by natural language query
kb_write(topic, entity_type, name, data)	Write/update a record (merges with existing)
kb_load(topic, entity_type, name)	Load one specific record
kb_topics()	List all KB topics and record counts
kb_schema(topic, entity_type?)	Show field schema for an entity type
corpus_status(topic)	Show KB size and record counts
kb_backup(dry?)	Mirror KB to OneDrive

Bring Your Own KB

Kilonova doesn't care what you store. Define your own schemas:

// kb/my_topic/schemas/component.json
{
  "name": {"type": "string", "description": "Component name"},
  "file": {"type": "string", "description": "Path to file"},
  "purpose": {"type": "string", "description": "What it does"},
  "dependencies": {"type": "array", "description": "What it depends on"}
}

Then write records to it and search them naturally.

Part of the Kilonova Ecosystem

Kilonova MCP is the free, standalone KB layer extracted from Milna OS — a full BYOK multi-model AI terminal. If you want the whole thing (parallel model legs, distillation engine, web ingestion, local+cloud hybrid inference), check out Milna OS.

MIT License · © AIM Studio