exocortex CLAUDE.md

Exocortex

Personal unified memory system — SQLite-backed, local-first, hybrid RAG retrieval.

Stack

• Monorepo: pnpm workspaces
• Packages: core (+ benchmark suite at core/src/benchmark/), cli, server, mcp, dashboard
• DB: Node built-in SQLite (node:sqlite)
• Embeddings: HuggingFace bge-small-en-v1.5 (local, 384 dims, no API key)
• Scoring: Reciprocal Rank Fusion (RRF) by default, fusing vector + FTS + graph ranked lists with recency/frequency/usefulness/valence/quality/goal-relevance boost. Legacy weighted-average mode available via scoring.use_rrf=false. All parseFloat calls have NaN guards with safe fallbacks.
• Dashboard: React + Vite, Neural Interface theme
• Tests: Vitest

Key Commands

• pnpm test — run all tests (~533 tests)
• pnpm build — build all packages
• pnpm lint — typecheck with tsc
• pnpm benchmark — run memory benchmark (requires ANTHROPIC_API_KEY)

MCP Setup

The MCP server works with any MCP-compatible tool (Claude Code, Codex, Gemini, Copilot, etc.). The entry point is packages/mcp/dist/index.js.

Claude Code (registered globally so memory tools are available in every session):

claude mcp add --scope user exocortex node /path/to/exocortex/packages/mcp/dist/index.js

Codex CLI (~/.codex/config.toml):

[mcp_servers.exocortex]
command = "node"
args = ["/path/to/exocortex/packages/mcp/dist/index.js"]

Gemini CLI (~/.gemini/settings.json):

{ "mcpServers": { "exocortex": { "command": "node", "args": ["/path/to/exocortex/packages/mcp/dist/index.js"] } } }

The project-level .mcp.json also exists as a fallback for this repo specifically (update the path after cloning).

Data Directory

All data stored in ~/.exocortex/ (DB + cached embedding models). Override model cache with EXOCORTEX_MODEL_DIR env var.

Dashboard Pages

• Dashboard (/dashboard) — memory storage overview (stats, charts, temporal data, tier distribution)
• Search (/) — hybrid search with tier quick-filters, advanced filters (content type, tier, date range, importance, namespace), bulk select/delete, inline new memory creation, keyboard shortcuts (/ to focus, arrow keys to paginate, Escape to cancel select)
• Timeline (/timeline) — chronological memory view with keyboard shortcuts
• Entities (/entities) — entity list by type with bulk select/delete, scrollable layout
• Entity Detail (/entities/:id) — entity info, relationship list + radial SVG graph, linked memories
• Graph (/graph) — interactive force-directed knowledge graph (canvas-based). Drag nodes, scroll to zoom, click to navigate
• Goals (/goals) — goal tracking with milestone progress
• Memory Detail (/memory/:id) — full memory view with inline edit mode (content, tags, importance), supersession diff view, soft-delete to trash
• Library (/library) — ingested reference documents with server-side search
• Sources (/sources) — memory attribution breakdown by provider/model/agent
• Analytics (/analytics) — quality trends, tier distribution, producer quality, tag health, embedding coverage
• Skills (/skills) — agent-created knowledge skills from Exocortex
• Trash (/trash) — archived/superseded memories with restore and permanent delete
• Chat (/chat) — RAG-powered Q&A with multi-turn conversation history, sources linked to memory detail
• Settings (/settings) — system configuration, export, and bulk import. API keys are masked in responses