⚡ Knowledge Master

Your codebase's memory. A local knowledge graph that gives AI agents real understanding of your architecture — not just text search.

Why

Every time you start a new AI chat, it forgets everything. You re-explain your architecture, conventions, dependencies. Knowledge Master gives your AI permanent, structured memory about your entire system.

Unlike flat RAG tools that return "chunks about X", Knowledge Master builds a graph — so it can answer "what breaks if I change X?" by traversing actual relationships.

What it does

• 🔍 Semantic search across all your code, docs, and configs
• 🕸️ Knowledge graph — relationships between services, people, repos, technologies
• 💥 Blast radius — "what depends on this service/file/technology?"
• 📏 Convention enforcement — detects and enforces your team's patterns
• 🤖 MCP server — plugs directly into AI agents (Kiro, Claude, Cursor)
• 🖥️ Web UI — search, browse, visualize your knowledge graph
• 🔒 Local-first — nothing leaves your machine

Prerequisites

Quick Start

# Install (pick one)
pipx install knowledge-master         # recommended (isolated, clean)
pip install knowledge-master           # or with pip

# Or via Homebrew (macOS)
brew install pipx && pipx install knowledge-master

# Or from source
git clone https://github.com/subzone/knowledge-master.git
cd knowledge-master
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# One command setup
km start

# Index your first repo
km index ~/path/to/your/project

# Search
km search "authentication flow"

# Check blast radius
km blast-radius postgres

# Start web UI with graph visualization
km serve

Requirements: Docker, Ollama, Python 3.11+

Features

Semantic Search with Graph Context

$ km search "how does auth work"
┌────────┬──────────────────────┬─────────────────────┬──────────────────────┐
│ Score  │ Source               │ Context             │ Preview              │
├────────┼──────────────────────┼─────────────────────┼──────────────────────┤
│ 0.847  │ src/auth/service.py  │ repo:myapp, by:Alex │ JWT token validat... │
│ 0.791  │ docs/auth.md         │ repo:myapp          │ Authentication f...  │
└────────┴──────────────────────┴─────────────────────┴──────────────────────┘

Blast Radius Analysis

$ km blast-radius auth-service
💥 Blast radius: auth-service
├── ⚙️ user-service (Service, via DEPENDS_ON)
├── ⚙️ payment-service (Service, via DEPENDS_ON)
├── 📦 frontend (Repo, via USES_SERVICE)
└── 👤 Alex (Person, via AUTHORED)

4 entities affected

Convention Enforcement

$ km check-conventions ~/my-project
  ✓ src/ directory (structure)
  ✓ separate test directory (testing)
  ✗ snake_case files (file-naming)
  ✓ Repository pattern (design-pattern)

1 convention(s) violated

Web UI & Graph Visualization

$ km serve
Knowledge Master UI → http://127.0.0.1:9999

Interactive force-directed graph showing your entire knowledge topology:

• 📦 Repos (blue) → 🔧 Technologies (red)
• ⚙️ Services (orange) → Dependencies
• 👤 People → Authorship
• 📏 Conventions (purple)

MCP Integration (AI Agents)

Add to your Kiro/Claude agent config:

{
  "mcpServers": {
    "knowledge": {
      "command": "km-server"
    }
  }
}

Your AI agent gets these tools:

• search — semantic search with graph context
• blast_radius — dependency analysis
• check_conventions — verify code follows team patterns
• index_repo — add new repos to the knowledge base

Architecture

┌─────────────────────────────────────────────────┐
│                  Your AI Agent                    │
│              (Kiro / Claude / Cursor)             │
└────────────────────┬────────────────────────────┘
                     │ MCP Protocol
┌────────────────────▼────────────────────────────┐
│              Knowledge Master                    │
│                                                  │
│  ┌──────────┐  ┌────────────┐  ┌────────────┐  │
│  │  Search  │  │Blast Radius│  │ Conventions│  │
│  └────┬─────┘  └─────┬──────┘  └─────┬──────┘  │
│       │               │               │         │
│  ┌────▼───────────────▼───────────────▼──────┐  │
│  │            FalkorDB (Graph + Vector)       │  │
│  │                                           │  │
│  │  [Repo]──USES_TECH──▶[Tech]              │  │
│  │    │                                      │  │
│  │    ├──DEFINES_SERVICE──▶[Service]         │  │
│  │    │                      │               │  │
│  │    ├──FOLLOWS──▶[Convention]              │  │
│  │    │                                      │  │
│  │  [Person]──AUTHORED──▶[Document]          │  │
│  │                          │                │  │
│  │                    [Chunk + Embedding]     │  │
│  └───────────────────────────────────────────┘  │
│                                                  │
│  ┌───────────────────────────────────────────┐  │
│  │         Ollama (nomic-embed-text)          │  │
│  └───────────────────────────────────────────┘  │
└──────────────────────────────────────────────────┘

Commands

What gets extracted automatically

When you index a repo, Knowledge Master detects:

Feature Status

Legend: ✅ Stable — ⚡ Basic (works, limited scope) — 🧪 Experimental (may change)

Comparison

Development

# Run tests
pytest

# Lint
ruff check knowledge_master/

# Run MCP server directly
python -m knowledge_master.server

# Run CLI directly
python -m knowledge_master.cli status

Security

Knowledge Master runs entirely on your machine. No data leaves localhost.

• All ports bound to 127.0.0.1 (not accessible from LAN)
• Ollama runs locally — no cloud API calls
• MCP server uses stdio (no network exposure)
• Optional API key auth for REST endpoints

# Enable API key auth
export KM_API_KEY=$(openssl rand -hex 32)
km serve

See SECURITY.md for full security model, risks, and hardening guide.

Troubleshooting

License

MIT