🧠 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

✅ 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

👥 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

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

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

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

If empty, run npm run db:sync

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

❓ FAQ

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

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

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

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"

🤝 Contributing

All contributions welcome:

• 🐛 Bug reports
• 💡 Feature ideas & suggestions
• 📝 Documentation improvements
• 🔧 Code contributions

Have an idea? Open a GitHub Issue — we discuss everything!

Fork → Branch → PR → We'll review and merge together.

🔍 Similar Projects

If Cortex isn't the right fit, check out Zep — they solve a similar problem (agent context/memory) with a different approach. We discovered them after building Cortex and found the ideas surprisingly similar. Worth exploring if you need alternatives!

💖 Support

🔗 Links

GitHub · Issues · LinkedIn

Made with ❤️ by Denys Medvediev

⭐ Star this repo if it helps you! ⭐