AI Lab - Local-First RAG Second Brain

A retrieval-augmented knowledge base that runs entirely on your machine. It ingests markdown and an Obsidian vault, embeds every chunk locally with no API key, stores the vectors in SQLite, and answers semantic queries over hybrid keyword + vector search. It plugs into Claude Code over MCP so an AI assistant can pull your own notes before it answers.

No cloud. No API key for retrieval. Your notes never leave the machine.

$ npm run search "how do I keep my notes private without a cloud API"

[note] Local Embeddings and Local LLMs  (score 0.550)
  You do not have to send your notes to a cloud API to embed them. transformers.js
  runs sentence-embedding models directly in Node with no API key and no network...

That match came from pure semantic similarity - the query shares no keywords with the note title.

What it demonstrates

Capability	How
RAG	Ingest -> chunk by heading -> embed -> retrieve -> assemble context. src/ingest.ts, src/search.ts
Vector DB	Embeddings stored as BLOBs in SQLite; brute-force cosine scan + FTS5 keyword index in one file. src/db.ts
Local embeddings (key-free)	all-MiniLM-L6-v2 (384-dim) via transformers.js - runs on CPU, no network after first download. src/embeddings.ts
Second brain -> Obsidian	Point OBSIDIAN_VAULTS at a vault root; every note becomes retrievable. Content-hashing re-embeds only what changed. src/ingest.ts
Exposed to Claude Code (MCP)	kb_search and kb_context tools an assistant calls on its own. src/mcp-server.ts

Quickstart

npm install                       # native build needs Python <= 3.13
npm run ingest                    # embeds the bundled sample notes
npm run search "vector search"    # semantic + keyword retrieval
npm run ask "what is a second brain"   # assembled context block
npm run stats

Index your own Obsidian vault:

OBSIDIAN_VAULTS="$HOME/Documents/My Vault" npm run ingest

Wire it into Claude Code as a tool:

claude mcp add ai-lab -- npx tsx /absolute/path/to/ai-lab/src/mcp-server.ts

How retrieval works

1. Ingest - markdown is split on H1-H3 boundaries so each chunk stays topically coherent, with a hard cap (~1600 chars) on long sections.
2. Embed - each chunk is mean-pooled and L2-normalized into a 384-dim vector, so a raw dot product equals cosine similarity.
3. Store - vectors live as BLOBs next to their text in SQLite; an FTS5 virtual table indexes the same chunks for keyword recall.
4. Retrieve (hybrid) - the query is embedded and scored by cosine against every chunk; FTS5 keyword hits get a small boost. Keyword catches exact terms, vectors catch paraphrase - the blend beats either alone.
5. Assemble - top chunks are packed into a token-budgeted context block ready to ground a prompt.

Stack

• TypeScript + Node (ESM, run directly with tsx)
• @huggingface/transformers - local sentence embeddings
• better-sqlite3 - vectors + FTS5, single-file store
• @modelcontextprotocol/sdk - MCP server for Claude Code

More AI projects

Part of a wider set of AI tooling:

• nexus - 12-agent system for Claude Code, structured multi-agent roles
• diagrams - describe a diagram in plain English, get rendered Mermaid
• decks - AI slide-deck generator from a topic prompt
• score-card - technical-interview rubric with Claude feedback
• mimi - live meeting transcription with an AI summary
• local-apps - self-healing dev monitor with AI fix agents
• automations - visual node-based automation flow builder
• claude-live - Rust WebSocket server streaming Claude Code sessions