English · Tiếng Việt
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
📖 Documentation site Tiếng Việt ) ·
🎼 Conductor showcase
---
## 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](https://modelcontextprotocol.io/) 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](https://github.com/milla-jovovich/mempalace) (96.6%) with **$0 cost, no API key, fully offline**. MemPalace requires paid OpenAI embeddings; Cortex embeds through a local Ollama container 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
```typescript
// 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](https://github.com/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
- **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% |
| **Embedding** | **Local (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 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.
```bash
# 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:
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**:
| Provider | Model | Dim | Median / p90 per text | Cost |
|---|---|---|---|---|
| `ollama` **(bundled)** | `all-minilm` | 384 | **27ms / 64ms** | **Free** |
| `ollama` **(bundled)** | `bge-m3` | 1024 | 500ms / 638ms | **Free** |
| `gemini` | `gemini-embedding-001` | 768 | ~600ms via API | $$ |
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:
| Model | Index 1256 chunks | recall@1 | recall@3 | recall@5 | MRR |
|---|---|---|---|---|---|
| `all-minilm` | **43s** | 2/8 | 3/8 | 6/8 | 0.400 |
| `bge-m3` | 662s (15x) | **4/8** | **5/8** | 6/8 | **0.594** |
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
```mermaid
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 (32 tools)"]
TEL["Telemetry + Hints Engine"]
end
subgraph Services["Backend Services (Docker)"]
direction LR
GN["GitNexus bash -s -- start --daemon --hub https://
```
```powershell
# 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)
```bash
# 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
```
```powershell
# Windows
irm https://raw.githubusercontent.com/lktiep/cortex-hub/master/scripts/install-extension.ps1 | iex
```
Or download [`cortex-agent.vsix`](https://github.com/lktiep/cortex-hub/releases/latest/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`](docs/conductor/antigravity.md).
### One-Command Project Setup
```bash
# 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)
```bash
# Clone from your self-hosted server (or wherever you keep the repo)
git clone
cd cortex-hub
corepack enable && pnpm install
cp infra/.env.example infra/.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/conductor](https://lktiep.github.io/cortex-hub/conductor/) shows a plan becoming a task graph and running across machines.
📖 See [`docs/conductor.md`](docs/conductor.md) for current capabilities and limitations, and [`docs/conductor/setup.md`](docs/conductor/setup.md) to set up each machine. Before relying on it, run the [manual test checklist](docs/conductor/manual-test-checklist.md) on your own environments.
| Tool | Who calls it | Purpose |
|------|--------------|---------|
| `cortex_task_tree_create` | Lead | Create a whole plan (tasks, dependencies, review and user gates) in one call |
| `cortex_task_create` | Lead | Create a single task, optionally pinned to an agent |
| `cortex_agents` | Lead | List connected workers and live MCP sessions before choosing routes |
| `cortex_task_route` | Lead | Change how a task is routed, pick a fallback, clear an escalation |
| `cortex_task_review` | Lead | Approve or reject a task in review, or decide a lead gate |
| `cortex_task_cancel` | Lead | Cancel a task; its dependents stay blocked until rerouted |
| `cortex_task_submit_strategy` | Lead | Propose roles, subtasks and an execution plan for user review |
| `cortex_task_pickup` | Agent doing the work | Retrieve tasks assigned to the calling agent |
| `cortex_task_accept` | Agent doing the work | Accept an assigned task |
| `cortex_task_update` | Agent doing the work | Move a task through its lifecycle |
| `cortex_task_list` | Anyone | List tasks by project, status or assignee |
| `cortex_task_status` | Anyone | Full state of one task: subtasks, logs, history |
Parameters for each are in the [API reference](docs/api/hub-mcp-reference.md#conductor-tasks).
---
## Tech Stack
| Layer | Technology | Role |
|---|---|---|
| **MCP Server** | Hono on Node.js | Streamable HTTP + JSON-RPC, 32 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 — 32 tools
│ ├── dashboard-api/ # Hono API + mem9 + recipe pipeline
│ └── dashboard-web/ # Next.js dashboard
├── 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
| Document | Description |
|---|---|
| [`docs/architecture/overview.md`](docs/architecture/overview.md) | System architecture with diagrams |
| [`docs/architecture/recipe-system.md`](docs/architecture/recipe-system.md) | Recipe System (auto-learning from execution) |
| [`docs/architecture/llm-gateway.md`](docs/architecture/llm-gateway.md) | LLM Gateway design |
| [`docs/architecture/agent-quality-strategy.md`](docs/architecture/agent-quality-strategy.md) | Quality gates + scoring |
| [`docs/conductor.md`](docs/conductor.md) | Multi-agent conductor: status, quick tour, limitations |
| [`docs/conductor/setup.md`](docs/conductor/setup.md) | Conductor setup, per machine |
| [`docs/conductor/antigravity.md`](docs/conductor/antigravity.md) | Antigravity IDE, app and headless agy on macOS and Windows |
| [`docs/conductor/manual-test-checklist.md`](docs/conductor/manual-test-checklist.md) | Manual checks per environment (Windows, Docker, VSIX, live hub) |
| [Documentation site](https://lktiep.github.io/cortex-hub/) | Guides and reference for every command, hook and tool, in English and Vietnamese |
| [Conductor showcase](https://lktiep.github.io/cortex-hub/conductor/) | One-page tour of the Conductor |
| [`docs/api/hub-mcp-reference.md`](docs/api/hub-mcp-reference.md) | Full MCP tool API reference |
| [`benchmarks/README.md`](benchmarks/README.md) | Benchmark methodology + results |
| [`docs/guides/installation.md`](docs/guides/installation.md) | Full installation guide |
| [`docs/guides/use-cases.md`](docs/guides/use-cases.md) | Use cases + system requirements |
| [`docs/guides/free-llm-routing.md`](docs/guides/free-llm-routing.md) | Free LLM Provider Setup & Dynamic Routing Guide |
---
## 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
| Resource | Minimum | Recommended | Notes |
|----------|---------|-------------|-------|
| **CPU** | 2 vCPU | 4 vCPU | Qdrant vector search is CPU-bound |
| **RAM** | 4 GB | 8 GB | Qdrant + GitNexus + Node services |
| **Disk** | 20 GB | 50 GB | Vector indices grow with knowledge |
| **OS** | Ubuntu 22.04+ | Ubuntu 24.04 LTS | Any Linux with Docker 24+ |
**Best value:** Hetzner CX22 (~$4.50/mo) handles 3-5 agents.
---
## Cost
| Component | Cost | Notes |
|---|---|---|
| Linux server | $4.50/mo+ | Hetzner CX22 minimum |
| Cloudflare Tunnel | Free | No open ports |
| All services | Free | Self-hosted in Docker |
| LLM API calls | Pay-per-use | Your own keys, budget-controlled |
| **Total** | **~$5/mo + LLM usage** | |
---
## Contributing
See [Contributing Guide](docs/CONTRIBUTING.md) for development setup, commit conventions, and code standards.
## License
MIT © Cortex Hub Contributors
