---

📖 Overview

Cortex is a privacy-first desktop application that turns any folder of files into a queryable, spatial knowledge base. It ingests your code, documents, and databases; embeds them into a per-project vector graph; and lets you explore, question, and generate from them — using local models via Ollama / MLX or any cloud provider through a single API-key box. Everything is processed and stored on your machine.

Why Cortex?

• 🔒 Local-first & private — your files, embeddings, and chat history never leave your device.
• 🧠 GraphRAG, visualized — see your codebase as a 3D semantic graph, not a flat search box.
• 🛠️ One app, four studios — Immersive chat, a Studio IDE, an Omni-Document editor, and a Deep Research hub.
• 🔌 Universal AI routing — local Ollama, Apple MLX, or cloud (OpenAI / Anthropic / Gemini / Groq / xAI). Paste a key — Cortex detects the provider automatically.
• 🚀 Zero-terminal goal — ships as a one-click installer; model install/update/delete is built in.

[!NOTE] Cortex is built to run with Ollama for local models. Cloud providers are optional and configured in-app with your own API key.

---

✨ Features

🌐 Spatial Mapping & GraphRAG

Point Cortex at a folder and it parses source code, PDFs, DOCX/PPTX/XLSX, CSVs, and SQLite/.sql databases (with image OCR), embeds everything into a per-project ChromaDB vector store, and renders it as an interactive 3D force-graph with semantic clustering. Incremental SHA-256 caching means only changed files are re-processed.

💬 Immersive Chat with Live Artifacts

Ask questions grounded in your mapped project (HyDE + semantic retrieval). Responses render rich Markdown, syntax-highlighted code blocks, tables, and inline Chart.js charts & Mermaid diagrams. One-click export any answer to PDF.

🧑‍💻 Cortex Studio IDE

A VS Code-style workspace powered by Monaco: multi-tab editing, a real multi-terminal (split panes + detachable windows), a ~45-language code runner that uses your installed toolchains, and a visual debugger (DAP) with breakpoints, stepping, variables, call stack, and a Debug Console. A built-in Copilot agent offers three modes — Ask permission, Accept edits, and Plan mode — with live edits in open editors.

📑 Omni-Document Studio

A polymorphic editor: code files open in Monaco, while documents (.md / .txt / .docx) open in a themed Quill rich-text editor — one workspace, the right editor per file. It adds Grammarly-style grammar & style suggestions, AI ghost-text autocomplete and a one-click Continue writer, plus open / save / export. All imported and AI-streamed HTML is sanitized with DOMPurify.

🔬 Deep Research Hub

One click runs an autonomous research agent: web search → page crawl + readable-text extraction → TF-IDF / KMeans topic analysis → LLM synthesis — streamed straight into a new document over SSE (batched at 30 fps for smooth, jank-free writing). Turn a single question into a structured, sourced report without leaving the app.

📤 Generative Studio

Turn any answer or dataset into a native, downloadable artifact — no copy-pasting:

• 📄 PDF reports (ReportLab / fpdf2) — export any chat response or analysis.
• 📊 PPTX decks (python-pptx) with auto-generated matplotlib charts.
• 🗂️ CSV datasets — synthesize or reshape tabular data with a column-count control.
• 📝 DOCX documents (python-docx) — both client-side (offline) and server-side.
• Plus inline Chart.js charts & Mermaid diagrams rendered live in chat.

🧠 Memory Ledger

A persistent mem0-backed memory that lets the assistant remember you across sessions — your preferences, persona, and standing constraints are mined from chats and injected into future prompts. Fully under your control: view, add, and delete entries in Settings → Memory Ledger, or bulk-load facts via Import Vault. Stored locally and never uploaded.

🍳 Model Cookbook & Utilities

A hardware-aware Model Cookbook scans your RAM/VRAM and recommends one best-fit model per family, with one-click install / update / delete of Ollama models (no terminal). Model Compare runs blind A/B tests. A Utilities surface adds Notes & Tasks and draft-only Email & Calendar.

🔌 Universal AI Routing

Paste an API key and Cortex auto-detects the provider from the key prefix (sk-ant-, gsk_, AIza, xai-, sk-) and routes accordingly — no need to match the key to a dropdown.

---

🏗️ Architecture

A single FastAPI backend serves a vanilla-JS frontend and bundles the ML stack; a Tauri shell wraps it as a native desktop app with the backend running as a sidecar.

flowchart LR
    subgraph Desktop["Tauri Desktop Shell"]
        UI["Frontend (vanilla JS)\n3D Graph - Studio IDE - Docs - Chat"]
    end
    UI <-->|HTTP + WebSocket| API["FastAPI Backend"]
    API --> Ingest["Ingestion\nparse -> embed -> cluster"]
    Ingest --> Chroma["ChromaDB\nper-project vectors"]
    API --> RAG["GraphRAG retrieval (HyDE)"]
    RAG --> Chroma
    API --> Router["AI Router"]
    Router --> Ollama["Ollama / MLX (local)"]
    Router --> Cloud["litellm (cloud)"]
    API --> Mem["mem0 Memory Ledger"]

• WebSocket channels: /api/brain/ws (Copilot agent state machine), /api/terminal/ws (real PTY), /api/dap/ws (generic debug-adapter proxy).
• Storage (local, git-ignored): backend/storage/ — cache.db (diff cache), chroma_db/ (GraphRAG vectors), mem0_chroma/ + mem0.db (Memory Ledger).

---

🧰 Tech Stack

---

🚀 Getting Started (run from source)

Prerequisites: Python 3.11, Ollama running locally (for local models), and optionally Tesseract (image OCR).

# from the repository root (this folder)
python -m venv .venv && source .venv/bin/activate     # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# start the app (serves the full UI)
uvicorn backend.main:app --port 8077

Open http://localhost:8077 in your browser. Pull a model from the in-app Cookbook (or ollama pull llama3.1:8b), point Cortex at a folder, and start mapping.

The first launch downloads a small embedding model and loads the ML stack, so it can take a little while.

---

📦 Building the Desktop App

Cortex packages the Python backend with PyInstaller and wraps it with Tauri to produce a native installer (.dmg / .exe / .AppImage).

Prerequisites (build machine only — not shipped to users)

• Python env with requirements.txt installed
• PyInstaller — pip install pyinstaller
• Rust toolchain — https://rustup.rs
• Tauri CLI — cargo install tauri-cli --version "^2"
• App icons — src-tauri/icons/ (see the note below)
• Linux only — the WebKit dev libraries Tauri links against:

  # Debian / Ubuntu
  sudo apt install libwebkit2gtk-4.1-dev libsoup-3.0-dev build-essential \
    curl wget file libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev
  
  # Fedora
  sudo dnf install webkit2gtk4.1-devel libsoup3-devel openssl-devel \
    curl wget file libxdo-devel libappindicator-gtk3-devel librsvg2-devel
  

  scripts/build_installers.sh preflights these and prints the exact install line if any are missing.

[!IMPORTANT] The repo does not include src-tauri/icons/. Generate them once from any square PNG (≥ 1024×1024):

cargo tauri icon path/to/icon.png

This creates 32x32.png, 128x128.png, icon.icns, and icon.ico (required for the Windows installer).

🪟 Windows .exe (PowerShell)

# 1) Python backend -> standalone binary
python -m venv .venv; .\.venv\Scripts\Activate.ps1
pip install -r requirements.txt pyinstaller
pyinstaller --noconfirm cortex_backend.spec

# 2) Stage the backend as the Tauri sidecar (Tauri expects the target-triple suffix)
$triple = (rustc -Vv | Select-String 'host:').ToString().Split(' ')[-1]
New-Item -ItemType Directory -Force src-tauri\binaries | Out-Null
Copy-Item "dist\cortex-backend\cortex-backend.exe" "src-tauri\binaries\cortex-backend-$triple.exe"

# 3) Generate icons (first time only), then build the installer
cargo tauri icon path\to\icon.png
cd src-tauri
cargo tauri build

The installer lands in src-tauri\target\release\bundle\nsis\ (.exe). Run it — no terminal needed by the end user.

🍎 macOS / 🐧 Linux

One script builds for whichever Unix platform you run it on — it detects the OS and selects the right bundle targets:

./scripts/build_installers.sh

• macOS → src-tauri/target/release/bundle/{macos,dmg}/ (unsigned)
• Linux → src-tauri/target/release/bundle/{appimage,deb}/

[!NOTE] For a signed + notarized macOS .dmg, use ./scripts/build_macos.sh instead — it adds Developer-ID signing, notarization, stapling, and a deep-sign pass over the bundled Python binaries.

On Linux the app stores its data under $XDG_DATA_HOME/Cortex (default ~/.local/share/Cortex), and the folder picker uses zenity or kdialog — install one of them if "Browse" reports no dialog is available.

Voice transcription (optional): the bundled backend/workers/whisper.cpp source must be compiled for your platform (cmake) and a model downloaded for speech features; the rest of the app works without it.

---

⚙️ Configuration

In Settings → Cache & Index you can monitor index size and Purge Regional Indexes (clears the GraphRAG index + diff cache; never your Memory Ledger or notes).

---

🗺️ Roadmap

• Cross-project (multi-folder) graph merging
• More built-in chart types & dashboards
• Plugin API for custom tools
• Signed installers & auto-update

---

🤝 Acknowledgements

Built on the shoulders of Ollama, litellm, ChromaDB, sentence-transformers, Monaco Editor, Tauri, 3D-Force-Graph, and whisper.cpp.

---

📄 License

Released under the MIT License. See LICENSE for details.