{"id":46805622,"url":"https://github.com/gzoonet/cortex","last_synced_at":"2026-03-10T07:01:28.427Z","repository":{"id":342199795,"uuid":"1171146780","full_name":"gzoonet/cortex","owner":"gzoonet","description":"Local-first knowledge graph for developers. Watches your files, builds a knowledge graph with LLMs, lets you query across projects.","archived":false,"fork":false,"pushed_at":"2026-03-05T09:55:37.000Z","size":2889,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-05T11:12:23.565Z","etag":null,"topics":["cli","developer-tools","gzoo","knowledge-graph","llm","local-first","mcp","ollama","sqlite","web-dashboard"],"latest_commit_sha":null,"homepage":"https://github.com/gzoonet/cortex","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gzoonet.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"gzoonet"}},"created_at":"2026-03-02T23:21:14.000Z","updated_at":"2026-03-05T09:55:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gzoonet/cortex","commit_stats":null,"previous_names":["gzoonet/cortex"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/gzoonet/cortex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gzoonet%2Fcortex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gzoonet%2Fcortex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gzoonet%2Fcortex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gzoonet%2Fcortex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gzoonet","download_url":"https://codeload.github.com/gzoonet/cortex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gzoonet%2Fcortex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30326893,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T05:25:20.737Z","status":"ssl_error","status_checked_at":"2026-03-10T05:25:17.430Z","response_time":106,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","developer-tools","gzoo","knowledge-graph","llm","local-first","mcp","ollama","sqlite","web-dashboard"],"created_at":"2026-03-10T07:00:43.463Z","updated_at":"2026-03-10T07:01:28.372Z","avatar_url":"https://github.com/gzoonet.png","language":"TypeScript","funding_links":["https://github.com/sponsors/gzoonet"],"categories":[],"sub_categories":[],"readme":"# GZOO Cortex\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"social-preview.png\" alt=\"GZOO Cortex — Local-first knowledge graph for developers\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n**Local-first knowledge graph for developers.** Watches your project files,\nextracts entities and relationships using LLMs, and lets you query across\nall your projects in natural language.\n\n\u003e “What architecture decisions have I made across projects?”\n\u003e\n\u003e Cortex finds decisions from your READMEs, TypeScript files, config files,\n\u003e and conversation exports — then synthesizes an answer with source citations.\n\n## Why\n\nYou work on multiple projects. Decisions, patterns, and context are scattered\nacross hundreds of files. You forget what you decided three months ago. You\nre-solve problems you already solved in another repo.\n\nCortex watches your project directories, extracts knowledge automatically,\nand gives it back to you when you need it.\n\n## What It Does\n\n- **Watches** your project files (md, ts, js, json, yaml) for changes\n- **Extracts** entities: decisions, patterns, components, dependencies, constraints, action items\n- **Infers** relationships between entities across projects\n- **Detects** contradictions when decisions conflict\n- **Queries** in natural language with source citations\n- **Routes** intelligently between cloud and local LLMs\n- **Respects** privacy — restricted projects never leave your machine\n- **Web dashboard** with knowledge graph visualization, live feed, and query explorer\n- **MCP server** for direct integration with Claude Code\n\n## Quick Start\n\n### 1. Install\n\n```bash\nnpm install -g @gzoo/cortex\n```\n\nOr install from source:\n\n```bash\ngit clone https://github.com/gzoonet/cortex.git\ncd cortex\nnpm install \u0026\u0026 npm run build \u0026\u0026 npm link\n```\n\n### 2. Setup\n\nRun the interactive wizard:\n\n```bash\ncortex init\n```\n\nThis walks you through:\n- **LLM provider** — Anthropic, Google Gemini, Groq, OpenRouter, or Ollama (local)\n- **API key** — saved securely to `~/.cortex/.env`\n- **Routing mode** — cloud-first, hybrid, local-first, or local-only\n- **Watch directories** — which directories Cortex should monitor\n- **Budget limit** — monthly LLM spend cap\n\nConfig is stored at `~/.cortex/cortex.config.json`. API keys go in `~/.cortex/.env`.\n\n### 3. Register Projects\n\n```bash\ncortex projects add my-app ~/projects/app\ncortex projects add api ~/projects/api\ncortex projects list                       # verify\n```\n\n### 4. Watch \u0026 Query\n\n```bash\ncortex watch                               # start watching for changes\ncortex query \"what caching strategies am I using?\"\ncortex query \"what decisions have I made about authentication?\"\ncortex find \"PostgreSQL\" --expand 2\ncortex contradictions\n```\n\n### 5. Web Dashboard\n\n```bash\ncortex serve                               # open http://localhost:3710\n```\n\n### Excluding Files \u0026 Directories\n\nCortex ignores `node_modules`, `dist`, `.git`, and other common directories by default. To add more:\n\n```bash\ncortex config exclude add docs             # exclude a directory\ncortex config exclude add \"*.log\"          # exclude by pattern\ncortex config exclude list                 # see all excludes\ncortex config exclude remove docs          # remove an exclude\n```\n\n## How It Works\n\nCortex runs a pipeline on every file change:\n\n1. **Parse** — file content is chunked by a language-aware parser (tree-sitter for code, remark for markdown)\n2. **Extract** — LLM identifies entities (decisions, components, patterns, etc.)\n3. **Relate** — LLM infers relationships between new and existing entities\n4. **Detect** — contradictions and duplicates are flagged automatically\n5. **Store** — entities, relationships, and vectors go into SQLite + LanceDB\n6. **Query** — natural language queries search the graph and synthesize answers\n\nAll data stays local in `~/.cortex/`. Only LLM API calls leave your machine\n(and never for restricted projects).\n\n## LLM Providers\n\nCortex is **provider-agnostic**. It supports:\n\n- **Anthropic Claude** (Sonnet, Haiku) — via native Anthropic API\n- **Google Gemini** — via OpenAI-compatible API\n- **Any OpenAI-compatible API** — OpenRouter, local proxies, etc.\n- **Ollama** (Mistral, Llama, etc.) — fully local, no cloud required\n\n### Routing Modes\n\n| Mode | Cloud Cost | Quality | GPU Required |\n|------|-----------|---------|--------------|\n| `cloud-first` | Varies by provider | Highest | No |\n| `hybrid` | Reduced | High | Yes (Ollama) |\n| `local-first` | Minimal | Good | Yes (Ollama) |\n| `local-only` | $0 | Good | Yes (Ollama) |\n\nHybrid mode routes high-volume tasks (entity extraction, ranking) to Ollama\nand reasoning-heavy tasks (relationship inference, queries) to your cloud provider.\n\n## Requirements\n\n- **Node.js** 20+\n- **LLM API key** for cloud modes — Anthropic, Google Gemini, or any OpenAI-compatible provider\n- **Ollama** (for hybrid/local modes) — [install](https://ollama.ai/)\n\n## Configuration\n\nAll config lives in `~/.cortex/cortex.config.json`. API keys are in `~/.cortex/.env`.\n\n```bash\ncortex config list                       # see all non-default settings\ncortex config set llm.mode hybrid        # switch routing mode\ncortex config set llm.budget.monthlyLimitUsd 10  # set budget\ncortex config exclude add vendor         # exclude a directory from watching\ncortex privacy set ~/clients restricted  # mark directory as restricted\n```\n\nFull configuration reference: [docs/configuration.md](docs/configuration.md)\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `cortex init` | Interactive setup wizard |\n| `cortex projects add \u003cname\u003e [path]` | Register a project directory |\n| `cortex projects list` | List registered projects |\n| `cortex watch [project]` | Start watching for file changes |\n| `cortex query \u003cquestion\u003e` | Natural language query with citations |\n| `cortex find \u003cterm\u003e` | Find entities by name |\n| `cortex ingest \u003cfile-or-glob\u003e` | One-shot file ingestion |\n| `cortex status` | Graph stats, costs, provider status |\n| `cortex costs` | Detailed cost breakdown |\n| `cortex contradictions` | List active contradictions |\n| `cortex resolve \u003cid\u003e` | Resolve a contradiction |\n| `cortex models list/pull/test/info` | Manage Ollama models |\n| `cortex serve` | Start web dashboard (localhost:3710) |\n| `cortex mcp` | Start MCP server for Claude Code |\n| `cortex report` | Post-ingestion summary |\n| `cortex privacy set \u003cdir\u003e \u003clevel\u003e` | Set directory privacy |\n| `cortex config list/get/set` | Read/write configuration |\n| `cortex config exclude add/remove/list` | Manage file/directory exclusions |\n| `cortex db` | Database operations |\n\nFull CLI reference: [docs/cli-reference.md](docs/cli-reference.md)\n\n## Web Dashboard\n\nRun `cortex serve` to open a full web dashboard at `http://localhost:3710` with:\n\n- **Dashboard Home** — graph stats, recent activity, entity type breakdown\n- **Knowledge Graph** — interactive D3-force graph with clustering, click to explore\n- **Live Feed** — real-time file change and entity extraction events via WebSocket\n- **Query Explorer** — natural language queries with streaming responses\n- **Contradiction Resolver** — review and resolve conflicting decisions\n\n## MCP Server (Claude Code Integration)\n\nCortex includes an MCP server so Claude Code can query your knowledge graph directly:\n\n```bash\nclaude mcp add cortex --scope user -- node /path/to/packages/mcp/dist/index.js\n```\n\nThis gives Claude Code 4 tools: `get_status`, `list_projects`, `find_entity`, `query_cortex`.\n\n## Architecture\n\nMonorepo with eight packages:\n\n- **@cortex/core** — types, EventBus, config loader, error classes\n- **@cortex/ingest** — file parsers (tree-sitter + remark), chunker, watcher, pipeline\n- **@cortex/graph** — SQLite store, LanceDB vectors, query engine\n- **@cortex/llm** — Anthropic/Gemini/OpenAI-compatible/Ollama providers, router, prompts, cache\n- **@cortex/cli** — Commander.js CLI with 17 commands\n- **@cortex/mcp** — Model Context Protocol server (stdio transport)\n- **@cortex/server** — Express REST API + WebSocket relay\n- **@cortex/web** — React + Vite + D3 web dashboard\n\nArchitecture docs: [docs/](docs/)\n\n## Privacy \u0026 Security\n\n- Files classified as `restricted` are **never** sent to cloud LLMs\n- Sensitive files (.env, .pem, .key) are auto-detected and blocked\n- API key secrets are scanned and redacted before any cloud transmission\n- All data stored locally in `~/.cortex/` — nothing phones home\n\nFull security architecture: [docs/security.md](docs/security.md)\n\n## Built With\n\n- [SQLite](https://sqlite.org/) via better-sqlite3 — entity and relationship storage\n- [LanceDB](https://lancedb.com/) — vector embeddings for semantic search\n- [Anthropic Claude](https://anthropic.com/) — cloud LLM provider\n- [Google Gemini](https://ai.google.dev/) — cloud LLM provider (via OpenAI-compatible API)\n- [Ollama](https://ollama.ai/) — local LLM inference\n- [tree-sitter](https://tree-sitter.github.io/) — language-aware file parsing\n- [Chokidar](https://github.com/paulmillr/chokidar) — cross-platform file watching\n- [Commander.js](https://github.com/tj/commander.js/) — CLI framework\n- [React](https://react.dev/) + [Vite](https://vite.dev/) — web dashboard\n- [D3](https://d3js.org/) — knowledge graph visualization\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n\n## About\n\nBuilt by [GZOO](https://gzoo.ai) — an AI-powered business automation platform.\n\nCortex started as an internal tool to maintain context across multiple\nclient projects. We open-sourced it because every developer who works on\nmore than one thing loses context, and we think this approach — automatic\nfile watching + knowledge graph + natural language queries — is the right\nway to solve it.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgzoonet%2Fcortex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgzoonet%2Fcortex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgzoonet%2Fcortex/lists"}