🧠 Cortex: Open-Source AI Memory for your Codebase. Works with Claude CLI and others

Never Explain Your Codebase Twice.

🎯 What is Cortex · 👥 Who Needs It · ⚡ How It Works · 🚀 Quick Start · 📖 Docs · ❓ FAQ

🎯 What is Cortex?

Cortex is a semantic memory layer for AI coding assistants. It indexes your codebase into a vector database, so AI can find relevant code by meaning — not just keywords.

❌ Without Cortex

You: "Add payment processing"

Claude Code:
  → Reads CLAUDE.md (if exists)
  → Reads README.md
  → Maybe searches some files
  → Picks random agents (unpredictable)
  → Misses your PaymentService
  → Creates duplicate from scratch

</td> <td width="50%">

✅ With Cortex

You: "Add payment processing"

Claude Code:
  → Reads CLAUDE.md (finds Cortex instructions)
  → Loads Cortex memory agent
  → Queries MCP: "payment processing"
  → Gets: PaymentService, StripeClient, docs
  → Extends YOUR existing code

</td> </tr> </table>

👥 Who Needs Cortex?

| You should use Cortex if... | Why it helps | |----------------------------|--------------| | 🏢 Your codebase has 20+ files | AI can't hold everything in context | | 🔄 You've had AI rewrite existing code | Cortex finds it first | | 📚 You have docs AI keeps ignoring | Semantic search surfaces them | | 🤝 Your team has established patterns | AI learns and follows them | | 💸 You want free, local, private | No cloud, no API costs |

⚡ How It Works

flowchart TB
    subgraph INPUT["📁 Your Codebase"]
        A1[src/services/payment.ts]
        A2[src/utils/logger.ts]
        A3[docs/API.md]
        A4[README.md]
    end

    subgraph CORTEX["🧠 Cortex Processing"]
        B1[📄 Chunk Files]
        B2[🔢 Generate Embeddings]
        B3[(🗄️ Vector Database)]
    end

    subgraph QUERY["🤖 AI Assistant"]
        C1["User: Add email notifications"]
        C2[🔍 cortex_query]
        C3[📋 Results]
        C4[✅ Writes Code]
    end

    A1 & A2 & A3 & A4 --> B1
    B1 --> B2
    B2 --> B3

    C1 --> C2
    C2 -->|"search: notification"| B3
    B3 -->|"Found: NotificationService, EmailClient, logging patterns"| C3
    C3 --> C4

| Step | What Happens | |:----:|--------------| | 1️⃣ Index | Cortex chunks your code into ~1024 char pieces and creates semantic embeddings | | 2️⃣ Query | AI asks natural language questions: "how do we handle notifications?" | | 3️⃣ Build | AI receives relevant files and patterns, writes consistent code |

🚀 Quick Start

Step 1 · Add Cortex

cd your-project
git submodule add https://github.com/Remskill/Cortex.git cortex
cd cortex && cp .env.example .env && npm install

Step 2 · Configure Ignore Patterns

⚠️ Do this BEFORE syncing! Skips junk to be added to your memory.

cp docs/.cortexignore.default ../.cortexignore

Step 3 · Start Services

docker-compose up -d

Wait for model to be ready

⏱️ First run downloads the embedding model (~274MB, 2-5 min)

Step 4 · Initialize

npm run setup

Step 5 · Configure MCP

Create .mcp.json in your project root:

{
  "mcpServers": {
    "cortex": {
      "command": "npx",
      "args": ["tsx", "cortex/src/server.ts"],
      "env": {
        "DATABASE_URL": "postgres://cortex:cortex-dev-pass-123@localhost:5433/cortex",
        "OLLAMA_URL": "http://localhost:11434"
      }
    }
  }
}

Step 6 · Restart Claude Code

Run /exit and reopen. Verify with /mcp → should see cortex: connected

MCP Connected

Step 7 · Install Git Hook

🔴 Required — keeps AI memory in sync with your code

npm run hook:install

Step 8 · Create Cortex Memory Agent (Recommended)

💡 Why? Agents ensure Claude Code automatically queries Cortex before implementing features.

Option A: Using Claude Code CLI (recommended)

/agents
# → Select "Create new agent"
# → Follow prompts to create an agent for searching codebase patterns
# → Name it something like "cortex-memory-agent"

Option B: Copy example agent

# Copy the pre-built agent definition
cp cortex/docs/cortex-memory-agent.md .claude/agents/cortex-memory-agent.md

See docs/cortex-memory-agent.md for a complete agent example.

Step 9 · Add to CLAUDE.md

Tell Claude cli to always use your Cortex agent:

## Cortex Memory
**ALWAYS use the cortex-memory-agent before implementing ANY feature.**
This agent will query Cortex to find existing patterns and prevent code duplication.

Manual query example:
cortex_query("what you're building")

✅ Done!

cortex_query("how we handle API errors")
cortex_query("existing notification system")
cortex_query("database connection patterns")

🔄 Git Auto-Sync

After installing the hook, Cortex syncs automatically on every commit:

git commit -m "Add new feature"
# 🔄 Syncing changed files...
# ✅ src/feature.ts (12 chunks)
# ✅ docs/FEATURE.md (5 chunks)

| Benefit | Description | |---------|-------------| | 🤖 Zero effort | Happens automatically | | ⚡ Incremental | Only changed files | | 🎯 Always fresh | AI never sees stale code |

🛠️ MCP Tools Reference

| Tool | Purpose | |------|---------| | cortex_query | Search by meaning | | cortex_sync | Manual file sync | | cortex_stats | Database stats | | cortex_init | Health check | | cortex_list_files | List indexed files | | cortex_delete | Remove from index |

Query Examples

// Find existing implementations
cortex_query("payment processing")
cortex_query("user session management")

// Find patterns
cortex_query("how we handle errors in API routes")
cortex_query("state management approach")

// Find documentation
cortex_query("deployment process")
cortex_query("environment configuration")

💡 Tip: Be specific. "how we validate user input in forms" beats "validation".

📁 Configuration

.cortexignore

Controls what gets indexed. Copy the default:

cp cortex/docs/.cortexignore.default .cortexignore

Auto-excluded: node_modules, dist, build, .git, binary files

.cortexconfig.json (Optional)

{
  "maxFileSize": 52428800
}

52428800 = 50MB. Also accepts "50MB" string format.

💻 System Requirements

| Component | Minimum | |-----------|---------| | Docker | Docker Desktop or Engine | | RAM | 4GB (8GB recommended) | | Disk | ~2GB for models | | Node.js | v18+ |

🔧 Troubleshooting

<details> <summary>Services won't start</summary>

docker ps                    # Is Docker running?
docker-compose logs          # Check errors
docker-compose down && docker-compose up -d

</details> <details> <summary>No results from queries</summary>

cortex_stats()      // Check if data exists
cortex_list_files() // List what's indexed

If empty, run npm run db:sync

</details> <details> <summary>Emergency reset</summary>

docker-compose down -v   # Delete all data
docker-compose up -d     # Fresh start
npm run setup            # Reinitialize

</details>

❓ FAQ

<details> <summary>Is it really free?</summary>

Yes. MIT licensed, no API costs, no subscriptions. Embeddings run locally via Ollama.

</details> <details> <summary>Does my code leave my machine?</summary>

No. Everything runs in local Docker containers. Your code never leaves localhost.

</details> <details> <summary>What languages work?</summary>

All of them. Cortex indexes text content — TypeScript, Python, Go, Rust, Java, C++, Markdown, everything.

</details> <details> <summary>How is this different from grep?</summary>

Grep finds exact text matches. Cortex finds meaning:

Search "user authentication" → finds login handlers, JWT code, session management
Even if none of those files contain the words "user authentication"