kernal: Instructions file for Claude Code

Kernal — Developer Guide

What This Is

Kernal is an open-source MCP server that provides a structured knowledge graph for professionals. It stores people, organizations, activities, topics, actions, and notes in SQLite, connected by a generic relationship graph. Claude (or any LLM) drives extraction — the server is a clean data store, the LLM is the brain.

Repo: github.com/pintomatic/kernal License: MIT npm: @kernal/mcp (not yet published)

Architecture

User ──→ Claude ──→ MCP (stdio or HTTP) ──→ Kernal Server ──→ SQLite
                                                              ↑
                                            Dashboard ──→ REST API ──┘

• Local mode: Stdio transport, Claude Desktop connects directly
• Cloud mode: Express.js with StreamableHTTP MCP transport + REST API
• Dashboard: Vite + React app, connects to cloud server REST endpoints

Stack

• TypeScript 5.8, Node 18+
• SQLite via better-sqlite3 (local) / @libsql/client (Turso, cloud-ready)
• MCP SDK v1.27.1 (@modelcontextprotocol/sdk)
• Express.js 5 (cloud server)
• Zod (input validation)
• React 19 + Vite + Tailwind CSS 4 + react-force-graph-2d (dashboard)
• Vitest (testing)

Project Structure

kernal/
├── src/
│   ├── index.ts              # MCP stdio entry point
│   ├── server.ts             # McpServer + tool registration
│   ├── cloud.ts              # Express.js cloud entry point (HTTP + REST + MCP)
│   ├── db/
│   │   ├── schema.sql        # DDL (7 tables + FTS5 + triggers)
│   │   ├── adapter.ts        # DbAdapter interface
│   │   ├── local.ts          # better-sqlite3 adapter
│   │   └── turso.ts          # @libsql/client adapter (async)
│   ├── tools/
│   │   ├── index.ts          # registerTools() — all 13 tools
│   │   ├── remember.ts       # Store text + return extraction instructions
│   │   ├── add-person.ts     # Create/deduplicate person
│   │   ├── add-org.ts        # Create/deduplicate organization
│   │   ├── add-activity.ts   # Log interaction with linking
│   │   ├── add-action.ts     # Create follow-up/task
│   │   ├── link.ts           # Create relationship between entities
│   │   ├── recall.ts         # Search across all entity types
│   │   ├── people.ts         # Query contacts
│   │   ├── orgs.ts           # Query organizations
│   │   ├── activities.ts     # Query interactions
│   │   ├── actions.ts        # Query action items
│   │   ├── context.ts        # Full briefing (person or org)
│   │   └── correct.ts        # Update, delete, merge, reset
│   ├── extraction/
│   │   ├── prompt.ts         # Regex extraction engine (legacy, used by seed script)
│   │   └── resolver.ts       # Entity resolution (fuzzy match + Levenshtein)
│   ├── middleware/
│   │   └── auth.ts           # API key auth (timing-safe comparison)
│   └── utils/
│       ├── config.ts         # ~/.kernal/config.json management
│       └── format.ts         # Response formatting helpers
├── bin/
│   └── kernal.ts             # CLI: init, serve, status, export
├── dashboard/                # React dashboard (separate npm project)
│   ├── src/
│   │   ├── App.tsx           # Shell with nav, command bar, view routing
│   │   ├── components/
│   │   │   ├── Overview.tsx      # Stats grid + most connected + activity breakdown
│   │   │   ├── NetworkGraph.tsx  # Force-directed graph (react-force-graph-2d)
│   │   │   ├── Timeline.tsx      # Vertical activity timeline
│   │   │   └── ActionItems.tsx   # Actions grouped by urgency
│   │   ├── hooks/
│   │   │   └── useKernalApi.ts   # API fetch wrapper + types
│   │   └── lib/
│   │       └── intentRouter.ts   # NL command → view routing
│   └── vite.config.ts       # Proxies /api to cloud server
├── scripts/
│   └── seed-demo.ts          # Seed demo data (12 people, 18 orgs, 19 activities)
├── test/
│   └── resolver.test.ts      # 50 tests (resolution, extraction, tools, demo scenarios)
├── Dockerfile
├── package.json              # @kernal/mcp
└── tsconfig.json