KARP Graph Lite

A self-evolving personal knowledge graph for Claude Desktop.

Built by SoulDriver — Adelaide, Australia.

What Is This?

KARP Graph Lite is an MCP (Model Context Protocol) extension that gives Claude Desktop persistent, structured memory with semantic search. It runs as a local Node.js server, stores everything in a portable SQLite database on the user's machine, and serves a web UI for browsing, editing, and visualizing the knowledge graph.

The user installs it as a .mcpb bundle through Claude Desktop's extension system. No config files, no API keys, no cloud services. Unpack, install, done.

One sentence: Claude gets a brain that remembers across conversations, and the user gets a visual dashboard to see and manage everything Claude remembers.

Why Does This Exist?

Claude Desktop has a built-in memory system, but it's a black box. Users can't see what's stored, can't edit it, can't export it, can't structure it, and can't evolve it. Graph Lite fixes all of that:

Claude's Built-in Memory	KARP Graph Lite
Black box — user can't see what's stored	Transparent — full web UI, every node visible
Unstructured text blobs	Typed nodes: memory, todo, decision, insight, etc.
No editing or deletion	Full CRUD — create, read, update, delete
No export	Export to JSON, SQLite backup, snapshots
No connections between memories	Named relationships: `led_to`, `contradicts`, `part_of`
No search beyond keyword	Semantic search using vector embeddings
Fixed schema	Self-evolving — user adds custom types through conversation
Cloud-dependent	100% local, works offline, user owns the file

Security

Overview

KARP Graph Lite is a local-first tool. Your data never leaves your machine. There is no cloud sync, no telemetry, no analytics, no external API calls (except the one-time embedding model download on first run).

Web UI Protection

The web UI runs on localhost:3456 and is protected by a passphrase-based session authentication system:

Three-layer auth priority: (1) UI_PASSWORD environment variable → (2) Saved passphrase in auth.json → (3) First-run setup screen.
First-run setup — If no password is configured, the web UI shows a mandatory setup screen on first visit. Users must either set a passphrase or explicitly choose "Trust This Network" before they can access the dashboard. The UI cannot be used without making a conscious security decision.
Persistent config — Auth settings are saved to auth.json in the data folder. Once set, they persist across server restarts and extension reinstalls.
Password hashing — Passphrases are hashed using Node.js built-in crypto.scrypt (no external dependencies).
Session cookies — After successful login, a session cookie is set. Choose "Remember this device" for a 30-day session, or leave unchecked for a 24-hour session that expires when you close your browser.
Express middleware — All /api/* routes are protected. Unauthenticated requests receive a 401 response. During first-run setup, only auth endpoints are accessible.
Settings page — Change your passphrase or switch from trust mode to password mode at any time via Settings → Security.
MCP tools are unaffected — Claude Desktop communicates via stdio (standard input/output), not HTTP. The passphrase only protects the web UI, not Claude's ability to use the knowledge graph tools.

Network Safety

The Express server binds to 127.0.0.1 (localhost only). It is not accessible from other devices on your network by default.
Shared/public networks: If your machine's firewall allows inbound connections on port 3456, other devices on the same network could potentially access the UI. Always set a passphrase if you're on a shared or public network.
The "Remember this device" checkbox should only be used on a trusted personal computer.

Data at Rest

graph.db is a plain unencrypted SQLite file. Anyone with access to the file can read its contents.
Store your data folder in a location with appropriate file system permissions.
Do not store passwords, API keys, credit card numbers, or other secrets in the knowledge graph. It is designed for notes, insights, decisions, and structured knowledge — not credential storage.
Snapshots (backups) are also unencrypted SQLite copies in the snapshots/ subfolder.

Embedding Model

The BGE-small-en-v1.5 model (~130MB) is downloaded once from Hugging Face on first run and cached in your data folder under models/.
After the initial download, no further network requests are made by the extension.

What We Don't Collect

No usage analytics
No crash reporting
No telemetry
No user data transmission
No cloud accounts required

Your knowledge graph is yours. Period.

Architecture

Technology Stack

Component	Technology	Why
Runtime	Node.js (Claude Desktop's built-in)	Zero installation required
MCP Server	Custom stdio handler	Direct protocol implementation, no framework overhead
Database	sql.js (SQLite compiled to WebAssembly)	Universal compatibility — no native module compilation. We originally used better-sqlite3 but it crashes in Claude Desktop's bundled Node.js due to ABI mismatch
Embeddings	@xenova/transformers + BGE-small-en-v1.5	384-dimension vectors, ONNX runtime, ~130MB model cached locally
Web UI	Express serving a single HTML file	Dashboard, browse, D3 graph visualization, type manager, settings
Auth	Node.js crypto.scrypt	Passphrase hashing with zero external dependencies
Package	.mcpb bundle (ZIP with manifest)	Claude Desktop's native extension format

File Structure

karp-graph-lite/
├── package.json              # Dependencies: sql.js, @xenova/transformers, express
├── config/
│   └── manifest.json         # MCP extension manifest — tools, user config, metadata
├── server/
│   ├── index.js              # MCP protocol handler + Express web server + tool router
│   ├── database.js           # sql.js wrapper — schema, CRUD, migrations, snapshots
│   ├── embeddings.js         # BGE-small via transformers.js — embed, similarity
│   ├── search.js             # Semantic search, keyword search, re-embed pipeline
│   └── auth.js               # Passphrase auth, session management, Express middleware
├── ui/
│   └── index.html            # Single-file web UI (CSS + JS inline, D3.js for graph)
├── assets/
│   └── icon.png              # SoulDriver extension icon
├── scripts/
│   └── build_mcpb.js         # Bundle builder — stages, installs prod deps, zips
└── dist/
    └── karp-graph-lite.mcpb  # Distributable bundle

Data Storage (User's Machine)

[user-chosen-folder]/
├── graph.db                  # SQLite database (single file, portable)
├── snapshots/                # Auto and manual backups (SQLite copies)
└── models/                   # Cached BGE-small embedding model (~130MB)

The user chooses where this lives during installation. It's a single SQLite file. Copy it anywhere, back it up, share it. Zero lock-in. Data persists across extension reinstalls and updates.

MCP Tools (What Claude Sees)

Claude Desktop registers these 11 tools when the extension loads:

Knowledge Operations

Tool	Purpose	Key Behavior
`remember`	Store a new node	Accepts type, summary, detail, tags, importance, metadata. Auto-embeds for semantic search. Optional `connect_to` creates an edge in the same call.
`recall`	Semantic search	Embeds the query, compares against all stored vectors using cosine similarity. Returns ranked results with similarity scores. Finds by meaning, not keywords.
`forget`	Delete a node	Cascades: removes the node, its embedding, and all connected edges. Permanent.
`update`	Edit a node	Partial updates — only provided fields change. Metadata merges with existing. Auto re-embeds after update.
`connect`	Link two nodes	Named relationship (e.g. `led_to`, `contradicts`, `part_of`, `inspired_by`). Creates a directional edge.
`search`	Keyword search	LIKE-based search across summary, detail, context fields. Faster than recall but less intelligent.
`list`	Browse nodes	Filter by type, tags. Sort by created, updated, importance. Pagination via limit/offset.

Meta / Health Operations

Tool	Purpose
`kg_status`	Full health report: node counts by type, DB size, embedding coverage, available types, pending proposals, snapshot count
`propose_node_type`	Claude proposes a new custom type with field definitions. User approves in the web UI. Auto-snapshot before migration.
`snapshot`	Manual backup of the entire database. Auto-prunes to keep 20 most recent.
`re_embed`	Rebuild all vector embeddings. Used after adding new types or if search quality degrades.

Self-Evolving Schema

This is Graph Lite's defining feature. The knowledge graph ships with 6 base types, but users can add unlimited custom types through natural conversation with Claude.

Base Types (Shipped)

Type	Icon	Purpose
`memory`	💭	Personal reflections, wisdom, notes, letters
`todo`	✅	Tasks with status tracking
`decision`	⚖️	Choices made and their rationale
`insight`	💡	Patterns noticed, learnings, observations
`dev_session`	🔧	Structured daily work logs
`changelog`	📋	Versioned release notes

Custom Type Creation Flow

1. User and Claude are chatting naturally
2. They realize a new type would be useful
   Example: "I keep tracking recipes, can we make that a proper type?"

3. Claude calls propose_node_type:
   → type_name: "recipe"
   → display_name: "Recipe"  
   → icon: "🍳"
   → fields: [name, ingredients[], method, cuisine, prep_time, rating]

4. Proposal appears in the web UI as a banner
   → User reviews fields and clicks [Approve] or [Reject]

5. On approval:
   a. Auto-snapshot taken (safety net)
   b. Type definition added to type_definitions table
   c. Migration logged in migrations table
   d. Claude immediately has the new type available
   e. UI updates with new filter option

6. Claude can now: remember type="recipe" summary="Nonna's carbonara" ...

What This Means

Every user's knowledge graph becomes unique to their life and work:

A developer has dev_session, changelog (base) + maybe architecture_decision, bug_report
A chef has memory, insight (base) + recipe, ingredient_note, menu_plan
A lawyer has decision, todo (base) + case_brief, client_note, precedent
A teacher has insight, todo (base) + lesson_plan, student_note, curriculum_map
A researcher has insight, decision (base) + hypothesis, experiment, literature_note

Same engine, infinite shapes. Schema evolution negotiated in natural language — no database knowledge required.

Database Schema

All nodes share a single nodes table. Type-specific fields go in the JSON metadata column. This avoids table-per-type sprawl while keeping queries simple.

CREATE TABLE nodes (
    id TEXT PRIMARY KEY,
    type TEXT NOT NULL,
    summary TEXT NOT NULL,
    detail TEXT DEFAULT '',
    context TEXT DEFAULT '',
    tags TEXT DEFAULT '[]',
    importance REAL DEFAULT 0.5,
    created_at REAL NOT NULL,
    updated_at REAL NOT NULL,
    metadata TEXT DEFAULT '{}'
);

CREATE TABLE edges (
    id TEXT PRIMARY KEY,
    source_id TEXT NOT NULL,
    target_id TEXT NOT NULL,
    relationship TEXT NOT NULL,
    created_at REAL NOT NULL,
    FOREIGN KEY (source_id) REFERENCES nodes(id) ON DELETE CASCADE,
    FOREIGN KEY (target_id) REFERENCES nodes(id) ON DELETE CASCADE
);

CREATE TABLE embeddings (
    node_id TEXT PRIMARY KEY,
    vector BLOB NOT NULL,
    model TEXT NOT NULL,
    embedded_at REAL NOT NULL,
    FOREIGN KEY (node_id) REFERENCES nodes(id) ON DELETE CASCADE
);

CREATE TABLE type_definitions (
    type_name TEXT PRIMARY KEY,
    display_name TEXT NOT NULL,
    description TEXT DEFAULT '',
    fields TEXT NOT NULL DEFAULT '[]',
    icon TEXT DEFAULT '📝',
    is_base_type INTEGER DEFAULT 0,
    created_at REAL NOT NULL
);

CREATE TABLE pending_proposals (
    id TEXT PRIMARY KEY,
    type_name TEXT NOT NULL,
    display_name TEXT NOT NULL,
    description TEXT DEFAULT '',
    fields TEXT NOT NULL DEFAULT '[]',
    icon TEXT DEFAULT '📝',
    proposed_at REAL NOT NULL,
    status TEXT DEFAULT 'pending'
);

CREATE TABLE migrations (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    type_name TEXT NOT NULL,
    action TEXT NOT NULL,
    snapshot_path TEXT,
    fields_before TEXT,
    fields_after TEXT,
    created_at REAL NOT NULL
);

Embedding Pipeline

Model: BGE-small-en-v1.5 via @xenova/transformers (ONNX runtime), 384 dimensions
Text preparation: Node fields concatenated as [type] | summary | detail | context | Tags: ... | metadata..., truncated to 2000 chars
Search: Query embedded → cosine similarity against all stored vectors → ranked results
Auto-embed: On remember, on update, on startup (background job for missing vectors), on re_embed

Web UI

Served by Express on localhost:3456 (configurable). Single HTML file with inline CSS and JavaScript. Protected by passphrase authentication.

Page	Purpose
Dashboard	Stats cards, nodes by type breakdown, recent activity, pending proposal banners
Browse	Search bar (semantic + keyword), type filter chips, node cards, detail modal
Graph	D3.js force-directed visualization. Nodes colored by type, sized by importance. Click, drag, zoom.
Types	Base and custom types, pending proposals with approve/reject, instructions for creating types
Settings	Database info, snapshot management, JSON export, security status, link to full KARP platform

Relationship to Full KARP Platform

KARP Graph Lite is a free consumer tool. The full KARP Research Engine is an enterprise platform:

Aspect	Graph Lite	Full KARP
Embeddings	BGE-small (384d), local	BGE-large (1024d), server-side
Vector Storage	sql.js (SQLite WASM)	Enterprise-grade vector storage
AI Models	Claude Desktop (single model)	4 frontier models (Claude, GPT, Gemini, Grok)
Architecture	Single-user, local file	Multi-tenant, cloud, JWT auth, subscriptions
Use Case	Personal memory & notes	Institutional-grade research, 13-turn deliberation
Price	Free	Subscription tiers (PAYG to Enterprise)

Graph Lite is the free personal edition of the KARP knowledge graph architecture — the same design principles, scaled for individual use.

Product Family

KARP Inspector Lite — Semantic codebase search for Claude Desktop
KARP Graph Lite — Personal knowledge graph for Claude Desktop (this project)
Full KARP Platform — Multi-AI deliberation engine at souldriver.com.au

Key Engineering Decisions

sql.js over better-sqlite3

better-sqlite3 is a native C++ module that crashes in Claude Desktop's bundled Node.js due to ABI mismatch. Replaced with sql.js (SQLite compiled to WebAssembly) for universal compatibility. Trade-off: manual save-to-disk via debounced writes every 2 seconds.

Single `nodes` Table

Custom types store fields in the JSON metadata column rather than separate tables. Schema evolution is non-destructive — adding a type only requires an INSERT, not a CREATE TABLE.

No File Processing

Graph Lite does NOT process documents. Claude Desktop reads files natively. The flow is: user gives Claude a document → Claude reads it → Claude calls remember to store insights. File processing is planned as a separate product.

Passphrase Auth (Not OAuth/JWT)

Local tool needs local auth. Node's built-in crypto.scrypt handles hashing — zero external dependencies. Session cookies with configurable duration. No accounts, no cloud auth providers.

Current Status

Version: 1.1.0
Status: Stable — shipped and tested on Claude Desktop (Chat + Code tabs)

How to Build

cd Karp_Graph_Lite
npm install
npm run build    # Creates dist/karp-graph-lite.mcpb

How to Install

Open Claude Desktop
Settings → Extensions → Install Extension
Select dist/karp-graph-lite.mcpb
Choose a data folder when prompted
Set a passphrase (recommended for shared networks)
Open http://localhost:3456 to see your graph

How to Test (Manual)

DATA_PATH=./test_data UI_PORT=3456 UI_PASSWORD=yourpassphrase node server/index.js

License

MIT — SoulDriver (Adelaide, Australia)

The full KARP Research Engine uses enterprise-grade vector storage, multi-AI deliberation across four frontier models, and a knowledge graph architecture built for institutional-scale research. Graph Lite is the free personal edition.

souldriver.com.au

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
assets		assets
config		config
scripts		scripts
server		server
ui		ui
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

KARP Graph Lite

What Is This?

Why Does This Exist?

Security

Overview

Web UI Protection

Network Safety

Data at Rest

Embedding Model

What We Don't Collect

Architecture

Technology Stack

File Structure

Data Storage (User's Machine)

MCP Tools (What Claude Sees)

Knowledge Operations

Meta / Health Operations

Self-Evolving Schema

Base Types (Shipped)

Custom Type Creation Flow

What This Means

Database Schema

Embedding Pipeline

Web UI

Relationship to Full KARP Platform

Product Family

Key Engineering Decisions

sql.js over better-sqlite3

Single nodes Table

No File Processing

Passphrase Auth (Not OAuth/JWT)

Current Status

How to Build

How to Install

How to Test (Manual)

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Single `nodes` Table

Packages