lktiep/cortex-hub

Cortex Hub

Self-hosted AI Agent Memory + Code Intelligence Platform One MCP endpoint for every AI agent — persistent memory, AST-aware code search, quality enforcement.

Why · Features · Benchmarks · Quick Start · MCP Tools · Docs

---

Why Cortex?

Every AI coding agent works in isolation. Switch IDE, switch machine, switch project — the agent starts from zero. Your team’s hard-won decisions, bug fixes, and architectural patterns live and die inside individual chat sessions.

Cortex Hub is a self-hosted backend that gives every agent on your team persistent memory, shared knowledge, and cross-project intelligence via a single MCP endpoint:

        Claude Code    Cursor    Antigravity    Codex    Gemini
              │          │            │           │         │
              └──────────┴────────────┴───────────┴─────────┘
                                  │
                          ┌───────▼────────┐
                          │  Cortex Hub    │  ← one MCP endpoint for everything
                          │                │
                          │  Memory        │  Agents remember across sessions
                          │  Knowledge     │  Team shares bug fixes, patterns
                          │  Code Intel    │  Search any project's code by name
                          │  Quality Gates │  Enforce build/lint before commit
                          └────────────────┘

What this means in practice

New machine, instant context:

You: (fresh laptop, just cloned your project)
> /install           ← one command, MCP configured
> /cs                ← session starts

Cortex: "Resuming from last session. You were working on JWT rotation
         for the auth service. The team decided RS256 with 90-day expiry
         (stored by Dev B on March 15). Related: payment service uses
         the same pattern — see knowledge doc kdoc-4a2b."

You didn't bring any notes. You didn't clone the other repos.
Cortex remembered everything.

Cross-project code search without cloning:

You: "How does the backend handle user auth?"
Agent: cortex_code_search(query: "user auth", repo: "my-backend")
  → validateToken (Function) — src/middleware/auth.ts
  → refreshSession (Function) — src/services/session.ts

You never cloned my-backend. Cortex indexed it server-side
and searched the AST graph across 15 repos in 20ms.

Team knowledge that compounds:

Session 1 (Dev A, Claude Code):
  Fixed auth bug → stored knowledge: "JWT needs audience claim for mobile"

Session 2 (Dev B, Cursor, different project):
  Hit same auth issue → cortex_knowledge_search("JWT mobile") → instant fix

Session 3 (New hire, day 1):
  /cs → sees all team decisions, patterns, bug fixes
  Productive from hour one, not week three.

Retrieval quality: 96.0% R@5 on LongMemEval (500 questions, 6 categories) — matching MemPalace (96.6%) with $0 cost, no API key, fully offline. MemPalace requires paid OpenAI embeddings; Cortex runs the model in-process for free.

Zero data leaves your infrastructure. Self-hosted on a $5/month VPS behind Cloudflare Tunnel. Handles 5+ concurrent agents. Local embedding by default — no API keys, no network, no rate limits.

---

Features

🧠 Code Intelligence (GitNexus)

Smart cross-project search (added Apr 2026): call cortex_code_search(query: "...") without specifying repo and Cortex fans out across every indexed repo, runs both flow + symbol search, and returns a ranked list with refine hints. No more list_repos → guess → retry loops.

💾 Hierarchical Memory + Knowledge

Memory (per-agent, semantic recall across sessions):

• cortex_memory_store / cortex_memory_search
• Branch-scoped, project-scoped, with semantic deduplication

Knowledge Base (team-wide, structured):

• cortex_knowledge_store / cortex_knowledge_search
• Hall types (MemPalace-inspired): fact, event, discovery, preference, advice, general
• Temporal validity: valid_from / invalidated_at — query “what was true on date X”
• Supersession chain: mark old facts as replaced by new ones
• Timeline view: GET /api/knowledge/timeline — chronological exploration

// Store a fact with validity window
cortex_knowledge_store({
  title: "JWT secret rotation policy",
  content: "Rotate every 90 days, ...",
  hallType: "fact",
  validFrom: "2026-01-01"
})

// Later, when policy changes:
POST /api/knowledge/{id}/invalidate
  body: { supersededBy: "new-doc-id" }

🍳 Recipe System (Auto-Learning)

Inspired by HKUDS/OpenSpace — Cortex captures patterns from completed work automatically:

• Auto-capture on task.complete and session_end — if execution log shows a non-trivial workflow, an LLM extracts it as a reusable recipe
• Quality metrics: selection_count, applied_count, completion_count, fallback_count per doc
• Hybrid search ranking: vector_similarity * 0.6 + effective_rate * 0.3 + recency * 0.1 (only when selection_count >= 3)
• Evolution: docs with fallback_rate > 0.4 flagged for LLM rewrite via /health-check
• Lineage DAG: parent → derived → fixed relationships tracked

Dashboard /knowledge page shows the Recipe Health Panel — capture pipeline status, quality distribution, origin breakdown (manual/captured/derived/fixed), recent capture log.

🔀 LLM Gateway (CLIProxy)

• Multi-provider: Gemini, OpenAI, Anthropic, any OpenAI-compatible
• Ordered fallback chains with automatic retry (429/502/503/504)
• Format translation (Gemini ↔ OpenAI) handled transparently
• Budget enforcement — daily/monthly token limits from Dashboard
• Complexity-based routing — model: "auto" selects tier based on task

🛡️ Quality Gates

4-dimension scoring after every session:

Plus plan quality (cortex_plan_quality) — 8-criterion plan assessment before execution.

🔒 Compliance Enforcement

• Session compliance score — graded A/B/C/D at session end across 5 categories (Discovery, Safety, Learning, Contribution, Lifecycle)
• Adaptive hints — every MCP response includes context-aware suggestions
• Hook-enforced workflow — /cs blocks edits until knowledge + memory recall called
• Pre-commit gates — git commits blocked until quality gates pass

📊 Dashboard (13 pages)

• Overview — hero stats + per-project cards + recipe health
• Sessions — agent session list with API key tracking
• Quality — A→F grades with trend charts
• Knowledge — browse + Recipe Health Panel + capture log
• Projects — repo management with branch-aware indexing
• Providers / Usage / Keys / Organizations / Settings — full admin
• Mobile-responsive, dark theme

---

Benchmarks

Reproducible retrieval benchmarks against industry-standard datasets.

LongMemEval-S full 500 questions

Cortex matches MemPalace within 0.6 points on R@5 — while being free, offline, and 60x faster per embedding. NDCG@10 is 62% higher: when Cortex finds the answer, it places it at #1, not just somewhere in top 5.

MemPalace requires a paid OpenAI API key for embeddings. Cortex embeds through a local Ollama container — zero external network, zero cost, zero rate limits. The figures above were measured with the in-process Xenova/all-MiniLM-L6-v2 embedder that shipped at the time; see the note below.

# Run benchmark (no API key needed)
pnpm --filter @cortex/benchmarks bench:longmemeval

# Cleanup test data
pnpm --filter @cortex/benchmarks bench:longmemeval --cleanup

See benchmarks/README.md for full methodology, per-category breakdown, and results log.

Embedding Provider

Cortex supports two interchangeable embedding backends:

Every embedding goes through the internal LLM gateway (/api/llm/v1/embeddings), which resolves the provider from the model_routing table at request time. Point it at whichever backend you prefer from Settings → Providers:

The stack ships an ollama container with no host port, so local embedding needs no API key and never leaves the compose network.

Measured on this repo’s own index (1256 chunks of real source, 8 queries with a known answer file, 12 CPU cores, no GPU) — run pnpm bench:rerank in benchmarks/ to reproduce:

Read that as a ranking problem, not a retrieval problem: both models put the right file in the top 5 equally often, and bge-m3 only buys a better order for 15x the indexing cost. Pick all-minilm when a caller reads several hits, bge-m3 when it reads only the first — or keep all-minilm and fix the order with a reranker, below.

Reranking (optional)

Set TYPESAFE_API_KEY and /api/intel/code-search over-fetches vector candidates and reorders them by asking TypeSafe Jev (POST api.typesafe.ai/v1/systemone) whether each one actually contains what the query asked for — a typed yes/no with a calibrated probability, not a chat completion to parse. With no key the search path is byte-for-byte what it is today, and if a rerank call fails the candidate keeps its vector score, so an outage degrades to the current ordering rather than breaking search.

Note: an earlier release ran Xenova/all-MiniLM-L6-v2 in-process via @huggingface/transformers, selected with EMBEDDING_PROVIDER=local. That code was removed in 1fbfafc in favour of the gateway. Both EMBEDDING_PROVIDER and LOCAL_EMBEDDING_MODEL are now ignored — set the provider in the dashboard instead.

---

Architecture

graph TB
    subgraph Agents["AI Agents (any MCP client)"]
        AG["Antigravity"]
        CC["Claude Code"]
        CU["Cursor"]
        WS["Windsurf"]
        CX["Codex"]
    end

    subgraph Gateway["Hub MCP Server"]
        AUTH["API Key Auth"]
        ROUTER["Tool Router (31 tools)"]
        TEL["Telemetry + Hints Engine"]
    end

    subgraph Services["Backend Services (Docker)"]
        direction LR
        GN["GitNexusAST Graph :4848"]
        QD["QdrantVectors :6333"]
        DB["SQLiteWAL Mode"]
        CLIP["CLIProxyLLM Gateway :8317"]
    end

    subgraph Frontend["Dashboard"]
        DASH["Next.js 15(13 pages, static export)"]
    end

    Agents --> AUTH --> ROUTER --> TEL
    TEL --> Services
    DASH --> DB

Network Topology

Internet
  ├── localhost:8318 ─────────── Hub MCP Server
  └── localhost:3000 ─────────── Dashboard UI
                                    │
                              Cloudflare Tunnel
                                    │
                          ┌─────────┼─────────┐
                          │  Docker Compose    │
                          │  ├─ dashboard-web  │  Nginx (UI + API proxy)
                          │  ├─ cortex-api     │  Internal API + mem9
                          │  ├─ cortex-mcp     │  18+ MCP tools
                          │  ├─ qdrant         │  vectors + knowledge
                          │  ├─ gitnexus       │  AST code graph
                          │  ├─ llm-proxy      │  CLIProxy
                          │  └─ watchtower     │  auto-update
                          └────────────────────┘
                          Zero open ports on host.

---

MCP Tools

Cortex exposes 31 tools via a single MCP endpoint. The 19 below are the core set; the 12 Conductor tools (cortex_task_* and cortex_agents) are listed under Multi-Agent Conductor.

Cross-project search just works — no repo lookup needed:

cortex_code_search(query: "auth middleware jwt")  // scans ALL projects
cortex_code_search(query: "auth middleware jwt", repo: "cortex-hub")  // narrow to one

Full API reference: docs/api/hub-mcp-reference.md

---

Quick Start

Run Agent (No Clone Needed)

# macOS / Linux — starts a background worker (details: docs/conductor/setup.md)
curl -fsSL https://raw.githubusercontent.com/lktiep/cortex-hub/master/scripts/run-agent.sh | CORTEX_API_KEY= bash -s -- start --daemon --hub https://

# Windows
$env:CORTEX_API_KEY=""; iwr -useb https://raw.githubusercontent.com/lktiep/cortex-hub/master/scripts/run-agent.ps1 -OutFile $env:TEMP\run-agent.ps1; powershell -NoProfile -ExecutionPolicy Bypass -File $env:TEMP\run-agent.ps1 start --daemon --hub https://

Editor Extension (Antigravity IDE, VS Code, Cursor, Windsurf)

# macOS / Linux — installs the latest cortex-agent.vsix into every editor it finds
curl -fsSL https://raw.githubusercontent.com/lktiep/cortex-hub/master/scripts/install-extension.sh | bash

# Windows
irm https://raw.githubusercontent.com/lktiep/cortex-hub/master/scripts/install-extension.ps1 | iex

Or download cortex-agent.vsix and use Install from VSIX…. Each window can run its own agent with its own key: see docs/conductor/antigravity.md.

One-Command Project Setup

# macOS / Linux
curl -fsSL "https://raw.githubusercontent.com/lktiep/cortex-hub/master/scripts/install.sh" | bash

# Windows
iwr -useb "https://raw.githubusercontent.com/lktiep/cortex-hub/master/scripts/install.ps1" -OutFile $env:TEMP\install.ps1; powershell -NoProfile -ExecutionPolicy Bypass -File $env:TEMP\install.ps1

Or inside Claude Code: type /install

The installer:

• Auto-detects IDEs (Claude, Gemini, Cursor, Windsurf, VS Code, Codex)
• Configures MCP for each
• Installs enforcement hooks (.claude/hooks/*)
• Creates project profile with stack detection
• Auto-adds .gitignore entries for generated files
• Idempotent — safe to re-run

Server Setup (Admin)

# Clone from your self-hosted server (or wherever you keep the repo)
git clone 
cd cortex-hub
corepack enable && pnpm install
cp .env.example .env  # add API keys
cd infra && docker compose up -d

---

Multi-Agent Conductor

Cortex includes a multi-agent orchestration layer for cross-IDE task delegation. It is production-ready for the rows marked ✅ in the status table; 🔄 and 📋 rows are not.

🌐 Showcase: lktiep.github.io/cortex-hub shows a plan becoming a task graph and running across machines.

📖 See docs/conductor.md for current capabilities and limitations, and docs/conductor/setup.md to set up each machine. Before relying on it, run the manual test checklist on your own environments.

Parameters for each are in the API reference.

---

Tech Stack

---

Project Structure

cortex-hub/
├── apps/
│   ├── hub-mcp/                 # MCP Server — 31 tools
│   ├── dashboard-api/           # Hono API + mem9 + recipe pipeline
│   └── dashboard-web/           # Next.js dashboard (13 pages)
├── packages/
│   ├── shared-types/            # TS type definitions
│   ├── shared-utils/            # Logger, common utilities
│   └── shared-mem9/             # Embedding pipeline + vector store
├── benchmarks/                  # Reproducible benchmarks (LongMemEval, etc.)
├── infra/
│   ├── docker-compose.yml       # Full stack
│   └── Dockerfile.*             # Per-service builds
├── scripts/
│   ├── install.sh / .ps1        # Unified installer
│   ├── run-agent.sh / .ps1      # Worker bootstrap (downloads cortex-worker.mjs from your hub)
│   └── bootstrap.sh             # Admin setup
├── docs/
│   ├── architecture/            # Design docs (recipe, conductor, gateway)
│   ├── conductor.md             # Multi-agent orchestration (status table)
│   └── guides/                  # Onboarding, installation, use cases
├── templates/
│   ├── skills/install/          # /install slash command
│   └── workflows/               # Workflow templates (/code, /continue)
└── .cortex/                     # Project profile + agent identity

---

Docs

---

Real-World Scenarios

Solo dev, multiple projects

You maintain 5 repos across 3 languages. You fix a deployment bug in project A. Next week, project B has the same issue. Without Cortex, you debug from scratch. With Cortex:

cortex_knowledge_search("docker nginx 502 after restart")
→ "Nginx caches DNS at startup. Fix: resolver 127.0.0.11 valid=5s"
  (stored 6 days ago by you, in project A)

Time saved: 30 min per known bug. Across 5 projects, that’s hours/week.

Team of 3, shared codebase

Dev A refactors the auth middleware on Monday. Dev B starts a feature on Wednesday using the old auth pattern. Without Cortex, B’s code breaks and nobody knows why. With Cortex:

/cs → "Dev A refactored auth middleware on Monday. New pattern uses
       middleware.authenticate() instead of req.checkAuth(). See
       knowledge doc kdoc-8f2a for migration steps."

Zero “who changed this?” conversations. Zero broken PRs from stale patterns.

Onboarding a new team member

Day 1. New hire clones the repo. Runs /install. Opens Claude Code.

/cs → Cortex loads:
  - 47 team knowledge docs (deployment patterns, API conventions, known gotchas)
  - Recent session summaries (what's being worked on NOW)
  - Code intelligence across all indexed repos

New hire: "How does the payment flow work?"
cortex_code_search(query: "payment flow checkout")
→ 3 projects with relevant code, ranked by relevance, with file paths

Productive on day 1, not week 3. No “ask Dave, he knows how it works.”

Switching machines mid-task

Working on your Mac at the office. Continue on Windows VPS at home.

Same API key → same memory → same knowledge → same session context.
/cs resumes exactly where you left off.
No git stash, no notes, no "what was I doing?"

Multi-IDE workflow

Debug in Claude Code (deep reasoning). UI work in Cursor (fast iteration). Code review in Antigravity (visual). All three share the same Cortex backend:

Claude Code: stores finding → "Race condition in WebSocket reconnect"
Cursor:      picks up finding → applies fix in the UI component
Antigravity: reviews the fix → stores quality feedback

Every agent builds on what the others learned. No repeated explanations.

---

System Requirements

Best value: Hetzner CX22 (~$4.50/mo) handles 3-5 agents.

---

Cost

---

Contributing

See Contributing Guide for development setup, commit conventions, and code standards.

License

MIT © Cortex Hub Contributors