gzoonet/cortex

**Local-first knowledge graph for developers.** Watches your project files,
extracts entities and relationships using LLMs, and lets you query across
all your projects in natural language.
> “What architecture decisions have I made across projects?”
>
> Cortex finds decisions from your READMEs, TypeScript files, config files,
> and conversation exports — then synthesizes an answer with source citations.
Why
You work on multiple projects. Decisions, patterns, and context are scattered
across hundreds of files. You forget what you decided three months ago. You
re-solve problems you already solved in another repo.
Cortex watches your project directories, extracts knowledge automatically,
and gives it back to you when you need it.
What It Does
- **Watches** your project files (md, ts, js, py, json, yaml) for changes
- **Extracts** entities: decisions, patterns, components, dependencies, constraints, action items
- **Infers** relationships between entities across projects
- **Detects** contradictions when decisions conflict
- **Queries** in natural language with source citations
- **Searches semantically** — blends keyword and vector (embedding) similarity so queries match by meaning, not just keywords (optional; see Semantic Search)
- **Routes** intelligently between cloud and local LLMs
- **Respects** privacy — restricted projects never leave your machine
- **Web dashboard** with knowledge graph visualization, live feed, and query explorer
- **MCP server** for direct integration with Claude Code
Quick Start
1. Install
If global install fails with EACCES, use a user prefix instead:
Or install from source:
Verify: cortex --version (current release: **0.8.1**)
2. Setup
Run the interactive wizard:
This walks you through:
- **LLM provider** — Anthropic, Google Gemini, DeepSeek, Groq, OpenRouter, or Ollama (local)
- **API key** — saved securely to ~/.cortex/.env
- **Routing mode** — cloud-first, hybrid, local-first, or local-only
- **Watch directories** — which directories Cortex should monitor
- **Budget limit** — monthly LLM spend cap
cortex init writes global config to ~/.cortex/cortex.config.json. API keys go in ~/.cortex/.env.
3. Register Projects
4. Ingest, Watch & Query
**Backfill existing files first** — the watcher only picks up new changes:
| Command | What it does |
|---------|-------------|
| cortex serve | Web dashboard + API + file watcher (ignoreInitial — no re-ingest on start) |
| cortex watch | CLI-only file watcher (no dashboard) |
| cortex ingest | One-shot ingestion; events do **not** appear in the Live Feed |
> **Don't run watch and serve together** — they compete for file changes.
> The Live Feed shows real-time events from cortex serve only (file saves while the server is running).
5. Web Dashboard
Remote access:
Auth is enforced automatically on non-localhost hosts. A bearer token is auto-generated and saved to ~/.cortex/.env (read it with grep CORTEX_SERVER_AUTH_TOKEN ~/.cortex/.env). Open the dashboard once with http:// :3710/?token= — the token is embedded only for requests that already prove possession of it and is then kept for the browser tab (so anonymous visitors never receive it). API/WebSocket calls behind a reverse proxy use Authorization: Bearer .
Excluding Files & Directories
Cortex ignores node_modules, dist, .git, and other common directories by default. To add more:
How It Works
Cortex runs a pipeline on every file change:
1. **Parse** — file content is chunked by a language-aware parser (tree-sitter for code, remark for markdown)
2. **Extract** — LLM identifies entities (decisions, components, patterns, etc.)
3. **Relate** — LLM infers relationships between new and existing entities
4. **Detect** — contradictions and duplicates are flagged automatically
5. **Store** — entities, relationships, and vectors go into SQLite + LanceDB