cortex

Ein selbst gehostetes Gehirn für einen Haushalt oder ein Team: ein Dashboard, auf dem Menschen miteinander chatten und mit einem Agenten, der ihre gemeinsamen Notizen gelesen hat — auf deinem eigenen Modell, auf deiner eigenen Maschine.

Status: Alpha. Die API- und Konfigurationsoberfläche stabilisiert sich; erwarte breaking changes zwischen Minor-Versionen. Die Index- und Checkpoint-Formate sind Wegwerf-Caches — das Löschen von .cortex/ verliert Unterhaltungen, niemals Notizen.

pip install cortxai
cortex setup                 # wizard: brain dir, model endpoint, admin account
cortex serve --host 0.0.0.0  # dashboard on :8642

Oder bash install.sh (pipx/uv/venv-Autoerkennung), oder docker compose up nach dem einmaligen cortex setup /brain, das in docker-compose.yml dokumentiert ist.

Was es nicht tut: cortex hostet kein Modell — du bringst einen Endpunkt mit: Ollama, vLLM, LM Studio, einen LiteLLM-Proxy, OpenRouter oder die Anthropic-API. Vektorsuche ist exakte Kosinus-Ähnlichkeit im Prozess, richtig für persönliche und Team-große Gehirne, falsch für Millionen von Chunks. Vault-Bearbeitungen folgen dem Last-Writer-Wins-Prinzip mit Konflikterkennung (ein 409 und ein Banner), nicht Git-tauglichem Merging. Der Kalender-Connector expandiert noch keine Wiederholungsregeln.

Das Dashboard

• Chat — private Threads mit dem Agenten. Er sucht, bevor er antwortet, streamt seine Tool-Aufrufe (⚙ search_brain … ✓ 33ms) und zitiert Dateien mit Pfad; ein Klick auf ein Zitat öffnet es in der Vault-Ansicht.

• Channels — Peer-Chat für die Personen im Gehirn. Erwähne @cortex und der Agent antwortet im Kanal, wobei er nur das gemeinsame Vault liest — niemals das persönliche Vault von jemandem.

• Vault — gemeinsame und persönliche Vaults, im Browser bearbeitet mit Obsidian-artigem Rendering: [[wikilinks]], ![[embeds]], > [!note] Callouts, Frontmatter, Aufgaben-Checkboxen, die zurückschreiben, #tags. Strg-S speichert; eine gleichzeitige Bearbeitung erhält ein Konflikt-Banner, kein stilles Überschreiben.

• Import — bring ein bestehendes Obsidian-Vault als Zip-Upload, eine Git-URL oder einen Serverpfad mit. .obsidian/, .git/ und Nicht-Vault-Dateitypen werden übersprungen.

• Admin — Konten (admin / member), Index-Statistiken.

Konten sind Benutzername + Passwort (scrypt), Sitzungen sind HttpOnly-Cookies. Jeder Benutzer sieht das gemeinsame Vault, sein eigenes Vault und Connector-Quellen — Suche, grep und der Agent sind pro Anfrage begrenzt, innerhalb der Abfrage gefiltert statt nachträglich beschnitten.

Related MCP server: claudecode-mcp

Der Agent-Stack

LangGraphs ReAct-Agent über LangChain-Chatmodelle, mit Gesprächszustand in einem AsyncSqliteSaver-Checkpoint pro Thread:

providers:
  local:
    kind: openai                    # Ollama, vLLM, LM Studio — one wire
    base_url: "http://localhost:11434/v1"
    chat_model: qwen3
    embed_model: nomic-embed-text
  router:
    kind: openrouter                # cloud aggregator, OpenAI wire
    api_key_env: OPENROUTER_API_KEY
    chat_model: anthropic/claude-sonnet-5
  claude:
    kind: anthropic                 # direct Anthropic Messages API
    api_key_env: ANTHROPIC_API_KEY
    chat_model: claude-sonnet-5
roles:
  chat: router
  embed: local

Ein LiteLLM-Proxy ist kind: litellm mit seiner base_url — sein Routing und seine Fallback-Richtlinie bleiben im Proxy, sodass cortex kein LiteLLM-SDK mit sich führt. Endpunkte werden nach Netzwerkfakten klassifiziert: private, Loopback-, CGNAT- und Tailscale-Adressen sind vertrauenswürdig; alles Öffentliche erhält eine deutliche Warnung, dass deine Notizen das Netzwerk verlassen.

Retrieval ist hybrid: SQLite-FTS5- und Vektor-Kosinus-Ranking getrennt, fusioniert mit Reciprocal Rank Fusion, beeinflusst durch Aktualität — das Design aus Cerebras' Wissensbasis. Der Index wird von Grund auf neu aufgebaut, wenn sich das Chunk-Schema oder das Embedding-Modell ändert, denn das stille Mischen von Vektorräumen ist Korruption. Kein Embedding-Endpunkt bedeutet Volltextsuche, die das auch sagt, keine vorgetäuschten Vektor-Scores.

Vier Möglichkeiten, es zu erweitern

Eine defekte Erweiterung wird gemeldet und isoliert, niemals fatal. Registrierung ist keine Autorisierung: Ein Tool, das etwas Sensibles berührt, behält seine eigenen Prüfungen innerhalb des Callables.

Verwalte sie über das Dashboard. Das nur für Admins zugängliche Extend-Panel listet jedes Plugin, jeden Skill, Connector und MCP-Server mit dem, was er bereitstellt, seinem Ladefehler, falls vorhanden, und einem Aktivierungs-Schalter, der deine Quelldatei niemals bearbeitet. Du kannst ein Plugin oder einen Connector im Browser schreiben: Es wird geladen, bevor es gespeichert wird, sodass Code, der nicht importiert werden kann, mit der eigenen Meldung des Loaders abgelehnt wird, statt den nächsten Turn still zu brechen, und ein erfolgreiches Speichern baut den Agenten neu auf, sodass das neue Tool ohne Neustart live ist. Connectors erhalten ein Einstellungsfeld und einen „Jetzt ausführen“-Button; MCP-Server erhalten ein Formular. In cortex.yaml definierte Server erscheinen schreibgeschützt — die Datei bleibt der Eigentümer dessen, was sie deklariert.

Das Speichern eines Plugins oder Connectors führt diesen Code auf dem Server als cortex-Benutzer aus. Das ist dieselbe Vertrauensstufe wie das Konfigurieren eines stdio-MCP-Servers, und genau deshalb ist das Panel nur für Admins. Vom Terminal aus erledigen cortex ext list, cortex ext disable plugin <name> und cortex ext delete dieselbe Verwaltung ohne Browser.

Cortex ist auch ein MCP-Server — claude mcp add home-brain -- cortex mcp --brain ~/brain gibt Claude Code, Cursor oder Hermes dieselbe Tool-Registry, im Umfang des Box-Besitzers.

Aufbau eines Gehirns

~/brain/
├── cortex.yaml        # providers, roles, mcp servers, connectors
├── vaults/shared/     # everyone's notes
├── vaults/<user>/     # each user's private vault
├── sources/           # connector output
├── skills/ plugins/ connectors/
└── .cortex/           # index, checkpoints, usage.jsonl — disposable cache

Sichere es, indem du den Ordner kopierst. Heim-Gehirn, Firmen-Gehirn, Vereins-Gehirn: drei Ordner, drei cortex serve-Prozesse.

Beobachtbarkeit

Jeder Modell- und Tool-Aufruf hängt JSONL an .cortex/usage.jsonl an, mit prompt_tokens/completion_tokens, wenn der Endpunkt sie meldet — fehlende Zählwerte bleiben fehlend, statt zu Nullen zu werden, was preflight für die Kalibrierung erwartet. Telemetrie lässt einen Aufruf niemals fehlschlagen.

Entwicklung

uv venv --python 3.12 && uv pip install -e '.[dev]'
.venv/bin/pytest                    # 102 tests
.venv/bin/ruff check src tests
cd web && npm install && npm run dev   # SPA dev server, proxies to :8642

Der Frontend-Vertrag steht in docs/product-spec.md; das Veröffentlichen einer Version ist RELEASING.md.

Dokumentation: unchained-labs.github.io/cortex · Marke: Unchained-Labs/branding · Lizenz: MIT