🧠 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

Loading

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

Services won't start

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

No results from queries

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

If empty, run npm run db:sync

Emergency reset

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

---

❓ FAQ

Is it really free?

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

Does my code leave my machine?

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

What languages work?

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

How is this different from grep?

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! ⭐