GZOO Cortex

Ein Local-First-Wissensgraph für Entwickler. Überwacht Ihre Projektdateien, extrahiert Entitäten und Beziehungen mithilfe von LLMs und ermöglicht es Ihnen, alle Ihre Projekte in natürlicher Sprache abzufragen.

„Welche Architektur-Entscheidungen habe ich projektübergreifend getroffen?“

Cortex findet Entscheidungen aus Ihren READMEs, TypeScript-Dateien, Konfigurationsdateien und Konversationsexporten – und fasst dann eine Antwort mit Quellenangaben zusammen.

Warum

Sie arbeiten an mehreren Projekten. Entscheidungen, Muster und Kontext sind über Hunderte von Dateien verstreut. Sie vergessen, was Sie vor drei Monaten entschieden haben. Sie lösen Probleme erneut, die Sie bereits in einem anderen Repository gelöst haben.

Cortex überwacht Ihre Projektverzeichnisse, extrahiert automatisch Wissen und gibt es Ihnen zurück, wenn Sie es brauchen.

Related MCP server: agentmako

Was es tut

• Überwacht Ihre Projektdateien (md, ts, js, json, yaml) auf Änderungen

• Extrahiert Entitäten: Entscheidungen, Muster, Komponenten, Abhängigkeiten, Einschränkungen, Aufgaben

• Leitet Beziehungen zwischen Entitäten über Projekte hinweg ab

• Erkennt Widersprüche, wenn Entscheidungen im Konflikt stehen

• Fragt in natürlicher Sprache mit Quellenangaben ab

• Routet intelligent zwischen Cloud- und lokalen LLMs

• Respektiert die Privatsphäre – eingeschränkte Projekte verlassen niemals Ihren Rechner

• Web-Dashboard mit Wissensgraph-Visualisierung, Live-Feed und Abfrage-Explorer

• MCP-Server für die direkte Integration mit Claude Code

Schnellstart

1. Installation

npm install -g @gzoo/cortex

Oder Installation aus dem Quellcode:

git clone https://github.com/gzoonet/cortex.git
cd cortex
npm install && npm run build && npm link

2. Einrichtung

Führen Sie den interaktiven Assistenten aus:

cortex init

Dieser führt Sie durch:

• LLM-Anbieter – Anthropic, Google Gemini, DeepSeek, Groq, OpenRouter oder Ollama (lokal)

• API-Schlüssel – sicher gespeichert unter ~/.cortex/.env

• Routing-Modus – Cloud-First, Hybrid, Local-First oder nur lokal

• Überwachungsverzeichnisse – welche Verzeichnisse Cortex überwachen soll

• Budgetlimit – monatliche Obergrenze für LLM-Ausgaben

Die Konfiguration wird unter ~/.cortex/cortex.config.json gespeichert. API-Schlüssel kommen in ~/.cortex/.env.

3. Projekte registrieren

cortex projects add my-app ~/projects/app
cortex projects add api ~/projects/api
cortex projects list                       # verify

4. Überwachen & Abfragen

cortex watch                               # start watching for changes
cortex query "what caching strategies am I using?"
cortex query "what decisions have I made about authentication?"
cortex find "PostgreSQL" --expand 2
cortex contradictions

5. Web-Dashboard

cortex serve                               # open http://localhost:3710

Dateien & Verzeichnisse ausschließen

Cortex ignoriert standardmäßig node_modules, dist, .git und andere gängige Verzeichnisse. Um weitere hinzuzufügen:

cortex config exclude add docs             # exclude a directory
cortex config exclude add "*.log"          # exclude by pattern
cortex config exclude list                 # see all excludes
cortex config exclude remove docs          # remove an exclude

Funktionsweise

Cortex führt bei jeder Dateiänderung eine Pipeline aus:

1. Parsen – Dateiinhalte werden durch einen sprachbewussten Parser in Chunks unterteilt (tree-sitter für Code, remark für Markdown)

2. Extrahieren – LLM identifiziert Entitäten (Entscheidungen, Komponenten, Muster usw.)

3. Verknüpfen – LLM leitet Beziehungen zwischen neuen und bestehenden Entitäten ab

4. Erkennen – Widersprüche und Duplikate werden automatisch markiert

5. Speichern – Entitäten, Beziehungen und Vektoren werden in SQLite + LanceDB abgelegt

6. Abfragen – Abfragen in natürlicher Sprache durchsuchen den Graphen und synthetisieren Antworten

Alle Daten bleiben lokal in ~/.cortex/. Nur LLM-API-Aufrufe verlassen Ihren Rechner (und niemals für eingeschränkte Projekte).

LLM-Anbieter

Cortex ist anbieterunabhängig. Es unterstützt:

• Anthropic Claude (Sonnet, Haiku) – über native Anthropic API

• Google Gemini – über OpenAI-kompatible API

• DeepSeek (Reasoner, Chat) – starkes Schlussfolgern, sehr erschwinglich

• Groq – schnelle Inferenz mit kostenlosem Kontingent

• Jede OpenAI-kompatible API – OpenRouter, lokale Proxys usw.

• Ollama (Mistral, Llama, etc.) – vollständig lokal, keine Cloud erforderlich

Routing-Modi

Der Hybrid-Modus leitet aufgaben mit hohem Volumen (Entitätsextraktion, Ranking) an Ollama und logikintensive Aufgaben (Beziehungsinferenz, Abfragen) an Ihren Cloud-Anbieter weiter.

Anforderungen

• Node.js 20+

• LLM-API-Schlüssel für Cloud-Modi – Anthropic, Google Gemini, DeepSeek, Groq oder ein beliebiger OpenAI-kompatibler Anbieter

• Ollama (für Hybrid-/lokale Modi) – installieren

Konfiguration

Die gesamte Konfiguration befindet sich unter ~/.cortex/cortex.config.json. API-Schlüssel befinden sich unter ~/.cortex/.env.

cortex config list                       # see all non-default settings
cortex config set llm.mode hybrid        # switch routing mode
cortex config set llm.budget.monthlyLimitUsd 10  # set budget
cortex config exclude add vendor         # exclude a directory from watching
cortex privacy set ~/clients restricted  # mark directory as restricted

Referenz zur vollständigen Konfiguration: docs/configuration.md

Befehle

Referenz zur vollständigen CLI: docs/cli-reference.md

Web-Dashboard

Führen Sie cortex serve aus, um ein vollständiges Web-Dashboard unter http://localhost:3710 zu öffnen mit:

• Dashboard-Startseite – Graph-Statistiken, kürzliche Aktivitäten, Aufschlüsselung der Entitätstypen

• Wissensgraph – interaktiver D3-Force-Graph mit Clustering, zum Erkunden anklickbar

• Live-Feed – Echtzeit-Ereignisse zu Dateiänderungen und Entitätsextraktion via WebSocket

• Abfrage-Explorer – Abfragen in natürlicher Sprache mit Streaming-Antworten

• Widerspruchs-Auflöser – widersprüchliche Entscheidungen überprüfen und auflösen

MCP-Server (Claude Code Integration)

Cortex enthält einen MCP-Server, damit Claude Code Ihren Wissensgraphen direkt abfragen kann:

claude mcp add cortex --scope user -- npx @gzoo/cortex mcp

Dies gibt Claude Code 12 Tools:

Architektur

Monorepo mit acht Paketen:

• @cortex/core – Typen, EventBus, Konfigurations-Loader, Fehlerklassen

• @cortex/ingest – Dateiparser (tree-sitter + remark), Chunker, Watcher, Pipeline

• @cortex/graph – SQLite-Speicher, LanceDB-Vektoren, Abfrage-Engine

• @cortex/llm – Anthropic/Gemini/OpenAI-kompatible/Ollama-Anbieter, Router, Prompts, Cache

• @cortex/cli – Commander.js CLI mit 18 Befehlen

• @cortex/mcp – Model Context Protocol Server (stdio-Transport, 12 Tools)

• @cortex/server – Express REST API + WebSocket-Relay

• @cortex/web – React + Vite + D3 Web-Dashboard

Architektur-Dokumentation: docs/

Privatsphäre & Sicherheit

• Als restricted (eingeschränkt) klassifizierte Dateien werden niemals an Cloud-LLMs gesendet

• Sensible Dateien (.env, .pem, .key) werden automatisch erkannt und blockiert

• API-Schlüssel werden vor jeder Cloud-Übertragung gescannt und geschwärzt

• Alle Daten werden lokal unter ~/.cortex/ gespeichert – nichts telefoniert nach Hause

Sicherheitsarchitektur: docs/security.md

Erstellt mit

• SQLite via better-sqlite3 – Entitäts- und Beziehungsspeicherung

• LanceDB – Vektoreinbettungen für semantische Suche

• Anthropic Claude – Cloud-LLM-Anbieter

• Google Gemini – Cloud-LLM-Anbieter (via OpenAI-kompatible API)

• DeepSeek – Cloud-LLM-Anbieter (Schlussfolgern + Chat)

• Groq – schnelle Cloud-Inferenz

• Ollama – lokale LLM-Inferenz

• tree-sitter – sprachbewusstes Dateiparsing

• Chokidar – plattformübergreifende Dateiüberwachung

• Commander.js – CLI-Framework

• React + Vite – Web-Dashboard

• D3 – Wissensgraph-Visualisierung

Mitwirken

Siehe CONTRIBUTING.md für Richtlinien.

Lizenz

MIT – siehe LICENSE

Über

Erstellt von GZOO – einer KI-gestützten Plattform für Geschäftsautomatisierung.

Cortex begann als internes Tool, um den Kontext über mehrere Kundenprojekte hinweg zu wahren. Wir haben es als Open Source veröffentlicht, weil jeder Entwickler, der an mehr als einer Sache arbeitet, den Kontext verliert, und wir glauben, dass dieser Ansatz – automatische Dateiüberwachung + Wissensgraph + Abfragen in natürlicher Sprache – der richtige Weg ist, um dies zu lösen.