@a13xu/lucid

MCP server for Claude Code — persistent memory, smart code indexing, model selection, and code quality validation. Works out of the box with zero configuration.

Token-efficient memory, code indexing, and validation for Claude Code agents — backed by SQLite + FTS5.

Stores a persistent knowledge graph (entities, relations, observations), indexes source files as compressed binary with change detection, retrieves minimal relevant context via TF-IDF or Qdrant, and validates code for LLM drift patterns. Supports TypeScript, JavaScript, Python, Vue, Nuxt. Optional LLMLingua-2 semantic compression reduces context tokens by 30–70% while preserving meaning.

Install

Requirements: Node.js 18+

# Option 1 — global install (recommended, faster startup)
npm install -g @a13xu/lucid
claude mcp add --transport stdio lucid -- lucid

# Option 2 — no install needed (uses npx on each start)
claude mcp add --transport stdio lucid -- npx -y @a13xu/lucid

Or add to .mcp.json in your project root:

{
  "mcpServers": {
    "lucid": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@a13xu/lucid"],
      "env": {
        "MEMORY_DB_PATH": "/your/project/.claude/memory.db"
      }
    }
  }
}

Default DB path: ~/.claude/memory.db

Quick start

1. "Index this project" → init_project()               → scans CLAUDE.md, package.json, src/**
2. Write code           → sync_file(path)               → compressed + hashed + diff stored
3. "What's relevant?"  → smart_context("auth flow")    → recall + code in one call, adaptive budget
4. "What model?"       → suggest_model("refactor auth") → haiku (lookup) or sonnet (reasoning)
5. "What changed?"     → get_recent(hours=2)            → line diffs of recent edits
6. "Where is X used?"  → grep_code("X")                → matching lines only, ~30 tokens
7. "What do we know?"  → recall("query")               → knowledge graph search

Tools (37)

Memory

Code indexing

Token optimization

Logic Guardian

Plans

Reward system

Code Quality Guard

Web Dev Skills

Token optimization in depth

How smart_context works (recommended)

query: "auth middleware"
         ↓
  1. recall(query)  — knowledge graph search (entities, relations)
         ↓
  2. TF-IDF score all indexed files against query
     (or Qdrant top-k if QDRANT_URL is set)
         ↓
  3. Boost recently-modified files (+0.3 score)
     Boost rewarded files (+0.25 score, decayed)
         ↓
  4. For each file within token budget:
       file < maxTokensPerFile  → return full source
       file > maxTokensPerFile  → return skeleton only
                                   (imports + signatures + TODOs)
                                   + relevant fragments around query terms
         ↓
  5. Optional: LLMLingua-2 compression (if enabled in config)
         ↓
  output: merged knowledge + code — budget: 2k/6k/12k by task_type

How get_context works (classic)

query: "auth middleware"
         ↓
  1. TF-IDF score all indexed files against query
     (or Qdrant top-k if QDRANT_URL is set)
         ↓
  2. Boost recently-modified files (+0.3 score)
         ↓
  3. Apply whitelist dirs filter (if configured)
         ↓
  4. For each file within token budget:
       file < maxTokensPerFile  → return full source
       file > maxTokensPerFile  → return skeleton only
                                   (imports + signatures + TODOs)
                                   + relevant fragments around query terms
         ↓
  output: ~500–2000 tokens  vs  5000–20000 for reading full files

Skeleton pruning (AST-based)

Large files are replaced with their structural skeleton:

// src/middleware/auth.ts [skeleton]
// Validates JWT tokens and attaches user to request context

import { Request, Response, NextFunction } from "express"
import { verifyToken } from "../services/jwt.js"

// — exports —
export function authMiddleware(req: Request, res: Response, next: NextFunction): void { … }
export function requireRole(role: string): RequestHandler { … }
export type AuthenticatedRequest = Request & { user: User }

vs reading the full 200-line file.

Qdrant vector search (optional)

Set env vars to enable semantic search instead of TF-IDF:

QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=your-key          # optional
OPENAI_API_KEY=sk-...            # for embeddings
EMBEDDING_MODEL=text-embedding-3-small  # optional

Or in .mcp.json:

{
  "mcpServers": {
    "lucid": {
      "command": "npx", "args": ["-y", "@a13xu/lucid"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Falls back to TF-IDF automatically if Qdrant is unreachable.

Semantic compression (optional)

LLMLingua-2 (microsoft/llmlingua-2-bert-base-multilingual-cased-meetingbank) identifies and drops semantically unimportant tokens before returning context to Claude — and before generating Qdrant embeddings.

Enable in lucid.config.json:

{
  "semanticCompression": {
    "enabled": true,
    "ratio": 0.5,
    "minLength": 300,
    "applyToEmbeddings": true
  }
}

Model is cached in ~/.lucid/models/ after first download. Falls back to uncompressed text on any error — safe to enable unconditionally.

Configuration (lucid.config.json)

Create in your project root to customize behavior:

{
  "whitelistDirs": ["src", "backend", "api"],
  "blacklistDirs": ["migrations", "fixtures"],
  "maxTokensPerFile": 600,
  "maxContextTokens": 8000,
  "recentWindowHours": 48,
  "semanticCompression": {
    "enabled": false,
    "ratio": 0.5
  }
}

Why no vectors by default?

Code has explicit structure — no NLP needed for most queries:

TF-IDF is fast, deterministic, and requires zero external services. Qdrant is available when you need semantic similarity across large codebases.

Why SQLite + FTS5?

Entity types

person · project · decision · pattern · tool · config · bug · convention

Relation types

uses · depends_on · created_by · part_of · replaced_by · conflicts_with · tested_by

HTTP daemon & auto-sync

Lucid can run as a background HTTP daemon (port 7821) for auto-syncing files without Claude's cooperation.

# Start daemon (watches for sync requests, serves REST API)
lucid watch

# With HTTP server
lucid watch --http

# Check status
lucid status

# Stop
lucid stop

REST API (when --http is active)

Auto-sync hook (lucid-sync)

init_project installs a Claude Code PostToolUse hook that calls lucid-sync after every file write/edit. The sync binary:

1. Tries HTTP sync (500ms timeout, if daemon running)
2. Falls back to direct SQLite sync (no daemon needed)

This keeps the knowledge graph current automatically — without relying on Claude remembering to call sync_file.

Skills enforcement

Lucid ships enforcement skills that install globally into ~/.claude/skills/ and activate in every project:

All skills use <HARD-GATE> blocks that prevent proceeding until required tools are called.

Install globally:

init_project()   # installs skills to ~/.claude/skills/ automatically

Debugging

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{},"clientInfo":{"name":"test","version":"1.0"},"protocolVersion":"2024-11-05"}}' \
  | npx @a13xu/lucid

In Claude Code: run /mcp — you should see lucid with 37 tools.

Contributing

Bug reports and pull requests are welcome on GitHub.

1. Fork the repo
2. npm install → npm run build
3. Test locally: claude mcp add --transport stdio lucid-dev -- node /path/to/lucid/build/index.js
4. Open a PR

Tech stack

• Runtime: Node.js 18+, TypeScript, ES modules
• MCP SDK: @modelcontextprotocol/sdk
• Database: better-sqlite3 (synchronous, WAL mode)
• Compression: Node.js built-in zlib (deflate level 9) + LLMLingua-2 semantic compression (optional)
• Hashing: SHA-256 via crypto (change detection)
• Ranking: TF-IDF (built-in) or Qdrant (optional, via REST)
• Semantic compression: @huggingface/transformers (ONNX Runtime, q8 quantization)
• HTTP daemon: Express 5 on port 7821 (optional)
• File watcher: chokidar
• Validation: zod
• Transport: stdio