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](benchmarks/README.md) (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)

| Capability | Tool | What It Does | |---|---|---| | Multi-project search | cortex_code_search | Omit repo to scan ALL indexed projects in parallel — ranked hints | | 360° symbol context | cortex_code_context | Callers, callees, execution flows for any function/class | | Blast radius | cortex_code_impact | See downstream impact before editing | | Pre-commit risk | cortex_detect_changes | Analyze uncommitted changes, find affected flows | | Direct graph queries | cortex_cypher | Cypher against the AST knowledge graph | | Multi-repo registry | cortex_list_repos | All indexed repos discoverable by name or slug | | Auto-reindex | cortex_code_reindex | Trigger after pushes |

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:

| Dimension | Weight | Measures | |-----------|--------|----------| | Build | 25 | Code compiles | | Regression | 25 | No existing tests broken | | Standards | 25 | Follows conventions | | Traceability | 25 | Changes linked to requirements |

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 Hub | MemPalace | |---|---|---| | R@5 | 96.0% | 96.6% | | R@10 | 97.8% | 98.2% | | NDCG@10 | 1.44 | 0.889 | | Embedding | Local (in-process, free) | OpenAI API (paid) | | API key needed | No | Yes | | Embedding speed | ~10ms/text | ~600ms/text | | Search (500 queries) | 52.6s | ~5 min | | Cost per run | $0 | ~$2-5 |

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 runs Xenova/all-MiniLM-L6-v2 in-process — zero network, zero cost, zero rate limits.

# 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](benchmarks/README.md) for full methodology, per-category breakdown, and results log.

Embedding Provider

Cortex supports two interchangeable embedding backends:

| Provider | Model | Dim | Speed | Cost | Quality | |---|---|---|---|---|---| | local (default) | Xenova/all-MiniLM-L6-v2 | 384 | ~10-50ms in-process | Free | 96.7% R@5 | | gemini | gemini-embedding-001 | 768 | ~600ms/text via API | $$ | 96.7% R@5 |

Local mode (default) runs the model in-process via @huggingface/transformers — no network, no API key, no rate limits, fully offline. Switch to Gemini via EMBEDDING_PROVIDER=gemini env var if needed.

---

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 (25 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 24 tools via a single MCP endpoint:

| # | Tool | Purpose | |---|------|---------| | 1 | cortex_session_start | Start session, get project context + relevant knowledge | | 2 | cortex_session_end | Close session with compliance grade | | 3 | cortex_changes | Check unseen changes from other agents | | 4 | cortex_code_search | Multi-project AST/symbol search with smart fan-out | | 5 | cortex_code_context | 360° symbol view | | 6 | cortex_code_impact | Blast radius analysis | | 7 | cortex_code_reindex | Trigger re-indexing | | 8 | cortex_list_repos | List indexed repos with names + slugs | | 9 | cortex_cypher | Direct graph queries | | 10 | cortex_detect_changes | Pre-commit risk analysis | | 11 | cortex_memory_search | Recall agent memories | | 12 | cortex_memory_store | Store findings | | 13 | cortex_knowledge_search | Search knowledge base (with hall_type + asOf filters) | | 14 | cortex_knowledge_store | Store knowledge with hall type + validity | | 15 | cortex_quality_report | Report build/test/lint results | | 16 | cortex_plan_quality | 8-criterion plan assessment | | 17 | cortex_tool_stats | Token savings + tool usage analytics | | 18 | cortex_health | Backend service health check |

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](docs/api/hub-mcp-reference.md)

---

Quick Start

Run Agent (No Clone Needed)

# macOS / Linux — interactive wizard
curl -fsSL https://raw.githubusercontent.com/lktiep/cortex-hub/master/scripts/run-agent.sh | bash -s -- launch

# Headless daemon with preset
curl -fsSL https://raw.githubusercontent.com/lktiep/cortex-hub/master/scripts/run-agent.sh | bash -s -- start --daemon --preset fullstack

# Windows
iwr -useb "https://raw.githubusercontent.com/lktiep/cortex-hub/master/scripts/run-agent.ps1" -OutFile $env:TEMP\run-agent.ps1
& $env:TEMP\run-agent.ps1 start

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; & $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 an experimental multi-agent orchestration layer for cross-IDE task delegation. It is not feature-complete — agents can already create/pickup tasks, but autonomous strategy execution and smart agent matching are still WIP.

📖 See [docs/conductor.md](docs/conductor.md) for current capabilities, limitations, and the rough edges to expect.

---

Tech Stack

| Layer | Technology | Role | |---|---|---| | MCP Server | Hono on Node.js | Streamable HTTP + JSON-RPC, 25 tools | | Code Intel | GitNexus | AST parsing, execution flow, Cypher graph | | Embeddings | mem9 + Qdrant | Vector search with semantic recall | | LLM Proxy | CLIProxy | Multi-provider with fallback chains | | App DB | SQLite (WAL) | Sessions, quality, usage, knowledge metadata | | API | Hono | Dashboard backend + mem9 in-process | | Frontend | Next.js 15 + React 19 | Static export, served by nginx | | Infra | Docker Compose | Service orchestration | | Tunnel | Cloudflare Tunnel | Zero open ports | | Hooks | Lefthook | Stack-aware git hooks | | Monorepo | pnpm + Turborepo | Build orchestration |

---

Project Structure

cortex-hub/
├── apps/
│   ├── hub-mcp/                 # MCP Server — 25 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
│

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [lktiep](https://github.com/lktiep)
- **Source:** [lktiep/cortex-hub](https://github.com/lktiep/cortex-hub)
- **License:** MIT
- **Homepage:** https://hub.jackle.dev

Install and usage instructions live in the source repository linked above.