GZOO Cortex

GZOO Cortex

Lokales Wissensdiagramm für Entwickler. Überwacht Ihre Projektdateien, extrahiert Entitäten und Beziehungen mithilfe von LLMs und ermöglicht Ihnen, alle Ihre Projekte in natürlicher Sprache abzufragen.

„Welche Architekturentscheidungen habe ich projektübergreifend getroffen?“

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

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 benötigen.

Was es tut

• Überwacht Ihre Projektdateien (md, ts, js, py, json, yaml) auf Änderungen
• Extrahiert Entitäten: Entscheidungen, Muster, Komponenten, Abhängigkeiten, Einschränkungen, Aktionspunkte
• Leitet Beziehungen zwischen Entitäten projektübergreifend ab
• Erkennt Widersprüche, wenn Entscheidungen kollidieren
• Fragt in natürlicher Sprache mit Quellenangaben ab
• Sucht semantisch – kombiniert Schlüsselwort- und Vektor-(Embedding)-Ähnlichkeit, sodass Abfragen nach Bedeutung und nicht nur nach Schlüsselwörtern übereinstimmen (optional; siehe Semantische Suche)
• Leitet intelligent zwischen Cloud- und lokalen LLMs weiter
• Respektiert Privatsphäre – eingeschränkte Projekte verlassen niemals Ihren Rechner
• Web-Dashboard mit Wissensgraph-Visualisierung, Live-Feed und Abfrage-Explorer
• MCP-Server für direkte Integration mit Claude Code

Schnellstart

1. Installation

npm install -g @gzoo/cortex

Wenn die globale Installation mit EACCES fehlschlägt, verwenden Sie stattdessen ein Benutzer-Präfix:

mkdir -p ~/.local
npm config set prefix ~/.local
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g @gzoo/cortex

Oder installieren Sie aus dem Quellcode:

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

Überprüfen: cortex --version (aktuelle Version: 0.8.1)

2. Einrichtung

Führen Sie den interaktiven Assistenten aus:

cortex init
cortex doctor                              # verify config, providers, and DB

Dieser führt Sie durch:

• LLM-Anbieter — Anthropic, Google Gemini, DeepSeek, Groq, OpenRouter oder Ollama (lokal)
• API-Schlüssel — sicher gespeichert in ~/.cortex/.env
• Routing-Modus — Cloud-First, Hybrid, Local-First oder Nur-Lokal
• Überwachungsverzeichnisse — welche Verzeichnisse Cortex überwachen soll
• Budgetlimit — monatliche LLM-Ausgabenobergrenze

cortex init schreibt die globale Konfiguration nach ~/.cortex/cortex.config.json. 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. Aufnehmen, Überwachen & Abfragen

Zuerst vorhandene Dateien auffüllen — der Watcher erfasst nur neue Änderungen:

cortex ingest "~/projects/app/src/**/*.ts"   # one-shot backfill
cortex serve                                 # dashboard + API + file watcher (recommended)

Befehl	Was er tut
cortex serve	Web-Dashboard + API + Datei-Watcher (ignoreInitial — keine erneute Aufnahme beim Start)
cortex watch	Nur-CLI-Datei-Watcher (kein Dashboard)
cortex ingest	Einmalige Aufnahme; Ereignisse erscheinen nicht im Live-Feed

Führen Sie watch und serve nicht zusammen aus — sie konkurrieren um Dateiänderungen. Der Live-Feed zeigt Echtzeit-Ereignisse nur von cortex serve (Dateispeicherungen, während der Server läuft).

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

Fernzugriff:

cortex serve --host 0.0.0.0

Die Authentifizierung wird automatisch auf Nicht-Localhost-Hosts erzwungen. Ein Bearer-Token wird automatisch generiert und in ~/.cortex/.env gespeichert (lesen Sie ihn mit grep CORTEX_SERVER_AUTH_TOKEN ~/.cortex/.env). Öffnen Sie das Dashboard einmal mit http://<host>:3710/?token=<token> — das Token wird nur für Anfragen eingebettet, die bereits dessen Besitz nachweisen, und dann für den Browser-Tab beibehalten (sodass anonyme Besucher es niemals erhalten). API/WebSocket-Aufrufe hinter einem Reverse-Proxy verwenden Authorization: Bearer <token>.

Ausschließen von Dateien & Verzeichnissen

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

Wie es funktioniert

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

1. Parsen — Dateiinhalte werden von einem sprachbewussten Parser in Blöcke zerlegt (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 vorhandenen Entitäten ab
4. Erkennen — Widersprüche und Duplikate werden automatisch markiert
5. Speichern — Entitäten, Beziehungen und Vektoren gehen in SQLite + LanceDB
6. Abfragen — Natürlichsprachliche Abfragen 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) — starke Argumentation, sehr erschwinglich
• Groq — schnelle Inferenz mit kostenlosem Kontingent
• Jede OpenAI-kompatible API — OpenRouter, lokale Proxys usw.
• Ollama (Mistral, Llama usw.) — vollständig lokal, keine Cloud erforderlich

Die Kostenverfolgung verwendet anbieterspezifische Tarife für DeepSeek-, Gemini-, Groq- und OpenRouter-Modelle – kein pauschaler Anthropic-Fallback.

Embeddings (für die semantische Suche) werden als separater Anbieter konfiguriert – unabhängig von Ihrem Chat-Modell – sodass Sie Chat auf DeepSeek und Embeddings auf OpenAI ausführen können. Siehe Semantische Suche.

Routing-Modi

Modus	Cloud-Kosten	Qualität	Ollama erforderlich
cloud-first	Variiert je nach Anbieter	Höchste	Nein
hybrid	Reduziert	Hoch	Ja
local-first	Minimal	Gut	Ja
local-only	$0	Gut	Ja

Im Cloud-First-Modus werden alle Aufgaben an Ihren Cloud-Anbieter weitergeleitet. Ollama ist nicht erforderlich und wird nur verwendet, wenn ein Budget-Fallback aktiviert ist. Der Hybrid-Modus leitet aufgaben mit hohem Volumen (Entitätsextraktion, Ranking) an Ollama und argumentationsintensive 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 — nur für die Modi hybrid, local-first oder local-only (installieren)

Konfiguration

Die Konfiguration ist geschichtet – spätere Quellen überschreiben frühere:

Priorität	Ort	Geltungsbereich
1	Integrierte Standardwerte	Global
2	~/.cortex/cortex.config.json	Global (erstellt von cortex init)
3	./cortex.config.json	Projektüberschreibungen (optional)
4	CORTEX_* Umgebungsvariablen	Sitzung

API-Schlüssel werden separat in ~/.cortex/.env gespeichert (niemals in der Konfigurations-JSON).

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
cortex doctor                            # validate setup

Vollständige Konfigurationsreferenz: docs/configuration.md

Semantische Suche (Embeddings)

Cortex kombiniert Schlüsselwort-(Volltext)-Suche mit Vektorähnlichkeit, sodass Abfragen nach Bedeutung und nicht nach exakten Wörtern übereinstimmen. Embeddings sind optional und standardmäßig deaktiviert – aktivieren Sie sie mit einem Cloud-Embeddings-Anbieter (keine lokale GPU oder Ollama erforderlich):

cortex config set llm.embeddings.enabled true
cortex config set llm.embeddings.baseUrl https://api.openai.com/v1
cortex config set llm.embeddings.model text-embedding-3-small
cortex config set llm.embeddings.apiKeySource env:OPENAI_API_KEY
cortex config set llm.embeddings.dimensions 1536
# then add the key to ~/.cortex/.env:
echo 'OPENAI_API_KEY=sk-...' >> ~/.cortex/.env

Der Embeddings-Anbieter ist unabhängig von Ihrem Chat-Anbieter – führen Sie Chat auf DeepSeek (oder Anthropic, Groq, …) und Embeddings auf OpenAI aus. Jeder OpenAI-kompatible Embeddings-Endpunkt funktioniert.

Neue Dateien werden automatisch eingebettet, sobald sie aufgenommen werden. Um den Index für einen Graphen zu erstellen, den Sie bereits aufgenommen haben, führen Sie eine einmalige Neuindizierung durch:

cortex reindex                 # all projects
cortex reindex my-app          # a single project

Befehle

Befehl	Beschreibung
cortex init	Interaktiver Einrichtungsassistent
cortex doctor	Konfiguration, Anbieter, Projekte, Geheimnisse und Datenbank validieren
cortex projects add/list/remove/show	Registrierte Projekte verwalten
cortex serve	Web-Dashboard + API + Datei-Watcher (Port 3710)
cortex watch [project]	Nur-CLI-Datei-Watcher
cortex ingest <file-or-glob>	Einmalige Dateiaufnahme (getrennt vom Live-Feed)
cortex reindex [project]	Den semantischen (Embedding-)Suchindex für vorhandene Entitäten neu erstellen
cortex query <question>	Natürlichsprachliche Abfrage mit Zitaten
cortex find <term>	Entitäten nach Namen finden
cortex status	Graph-Statistiken, Kosten, Anbieterstatus
cortex costs	Detaillierte Kostenaufschlüsselung
cortex contradictions	Aktive Widersprüche auflisten
cortex resolve <id>	Einen Widerspruch auflösen
cortex models list/pull/test/info	Ollama-Modelle verwalten
cortex mcp	MCP-Server für Claude Code starten
cortex report	Zusammenfassung nach der Aufnahme
cortex privacy set/list	Verzeichnisdatenschutz festlegen
cortex config list/get/set/validate	Konfiguration lesen/schreiben
cortex config exclude add/remove/list	Datei-/Verzeichnisausschlüsse verwalten
cortex stop / cortex restart	Laufende Watch-/Serve-Prozesse verwalten
cortex db	Datenbankoperationen

Vollständige CLI-Referenz: 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, aktuelle Aktivitäten, Aufschlüsselung nach Entitätstypen
• Wissensgraph — interaktiver D3-Force-Graph mit Clustering, zum Erkunden anklicken
• Live-Feed — Echtzeit-Ereignisse zu Dateiänderungen und Entitätsextraktion via WebSocket (nur von cortex serve)
• Abfrage-Explorer — natürlichsprachliche Abfragen mit Streaming-Antworten
• Widerspruchslöser — widersprüchliche Entscheidungen überprüfen und auflösen

Remote-Bereitstellung

Für den Zugriff außerhalb von localhost binden Sie an alle Schnittstellen und stellen Cortex hinter einen Reverse-Proxy:

cortex serve --host 0.0.0.0

Beispiel für eine nginx-Konfiguration — schützen Sie /api/ und /ws mit Basic Auth; stellen Sie statische Assets ohne Authentifizierung bereit (das Dashboard bettet das Bearer-Token in HTML ein):

location /api/ {
    auth_basic "Cortex";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://127.0.0.1:3710;
    proxy_set_header Authorization "Bearer $CORTEX_TOKEN";
}

location /ws {
    auth_basic "Cortex";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://127.0.0.1:3710;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

location / {
    auth_basic off;
    proxy_pass http://127.0.0.1:3710;
}

Setzen Sie CORTEX_SERVER_AUTH_TOKEN oder server.auth.token in der Konfiguration. Wenn die Authentifizierung aktiviert ist, bettet Cortex das Token in das Dashboard-HTML ein, sodass API- und WebSocket-Aufrufe automatisch authentifiziert werden.

MCP-Server (Claude Code Integration)

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

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

Dies gibt Claude Code 12 Werkzeuge:

Werkzeug	Beschreibung
cortex_ask	Natürlichsprachliche Fragen zu Ihren Projekten
get_status	Systemstatus und Graph-Statistiken
list_projects	Registrierte Projekte auflisten
find_entity	Entitäten nach Namen nachschlagen
query_cortex	Strukturierte Wissensgraph-Abfragen
get_contradictions	Erkannte Widersprüche auflisten
resolve_contradiction	Einen Widerspruch auflösen
search_entities	Entitäten mit Filtern suchen
ingest_file	Dateiaufnahme auslösen
add_project	Ein neues Projekt registrieren
remove_project	Registrierung eines Projekts aufheben
session_brief	Kontextzusammenfassung für die aktuelle Sitzung

Architektur

Monorepo mit acht Paketen:

• @cortex/core — Typen, EventBus, Konfigurationslader, 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
• @cortex/mcp — Model Context Protocol Server (stdio-Transport, 12 Werkzeuge)
• @cortex/server — Express REST API + WebSocket-Relay
• @cortex/web — React + Vite + D3 Web-Dashboard

Architekturdokumentation: docs/

Datenschutz & Sicherheit

• Als restricted klassifizierte Dateien werden niemals an Cloud-LLMs gesendet
• Sensible Dateien (.env, .pem, .key) werden automatisch erkannt und blockiert
• API-Schlüssel-Geheimnisse werden vor jeder Cloud-Übertragung gescannt und geschwärzt
• Alle Daten werden lokal in ~/.cortex/ gespeichert – nichts telefoniert nach Hause

Vollständige 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 (über OpenAI-kompatible API)
• DeepSeek — Cloud-LLM-Anbieter (Reasoning + Chat)
• Groq — schnelle Cloud-Inferenz
• Ollama — lokale LLM-Inferenz
• tree-sitter — sprachbewusste Dateianalyse
• 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 Werkzeug, um den Kontext über mehrere Kundenprojekte hinweg aufrechtzuerhalten. Wir haben es als Open Source veröffentlicht, weil jeder Entwickler, der an mehr als einer Sache arbeitet, Kontext verliert, und wir glauben, dass dieser Ansatz — automatische Dateiüberwachung + Wissensgraph + Abfragen in natürlicher Sprache — der richtige Weg ist, um dieses Problem zu lösen.