{"id":"4e69b73d-3bcf-4d6b-80a7-145c8b2ec3a4","slug":"remskill-cortex","kind":"mcp","name":"Cortex","summary":"Cortex: Open-Source AI Memory for your Codebase. Works with Claude CLI and others. It indexes your codebase into vector embeddings, enabling semantic search to find existing implementations and preven","owner":"Remskill","repoUrl":"https://github.com/Remskill/Cortex","license":"MIT","licenseTier":"permissive","trust":"community","stars":8,"match":null,"fewStars":false,"format":"mcp","createdAt":"2025-12-29T14:59:15.000Z","addedAt":"2026-10-21T08:13:00.712Z","logoUrl":"https://avatars.githubusercontent.com/u/145892229?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["search","developer-tools","memory-knowledge"],"tags":["ai-memory","claude-ai","claude-cli","claude-code","ollama","pgvector","rag","semantic-search"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T18:57:09.446Z","sample":false,"url":"https://conduits.dev/tools/remskill-cortex","language":"TypeScript","transports":["stdio"],"install":{"npm":"@remskill/cortex"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# 🧠 Cortex: Open-Source AI Memory for your Codebase.  Works with Claude CLI and others\n\n### Never Explain Your Codebase Twice.\n\n[![MIT License](https://img.shields.io/badge/License-MIT-22c55e?style=for-the-badge)](LICENSE)\n[![GitHub Stars](https://img.shields.io/github/stars/Remskill/Cortex?style=for-the-badge&logo=github&color=yellow)](https://github.com/Remskill/Cortex)\n[![Buy Me a Coffee](https://img.shields.io/badge/Support-Buy%20Me%20a%20Coffee-FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/denys_medvediev)\n\n![100% Local](https://img.shields.io/badge/🔒_100%25_Local-171717?style=flat-square)\n![100% Free](https://img.shields.io/badge/💰_100%25_Free-171717?style=flat-square)\n![Zero API Costs](https://img.shields.io/badge/🚀_Zero_API_Costs-171717?style=flat-square)\n\n[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)\n[![Node.js](https://img.shields.io/badge/Node.js_18+-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org/)\n[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-4169E1?style=flat-square&logo=postgresql&logoColor=white)](https://www.postgresql.org/)\n[![Docker](https://img.shields.io/badge/Docker-2496ED?style=flat-square&logo=docker&logoColor=white)](https://www.docker.com/)\n[![MCP](https://img.shields.io/badge/MCP-Protocol-8B5CF6?style=flat-square)](https://modelcontextprotocol.io/)\n\n[🎯 What is Cortex](#-what-is-cortex) · [👥 Who Needs It](#-who-needs-cortex) · [⚡ How It Works](#-how-it-works) · [🚀 Quick Start](#-quick-start) · [📖 Docs](#️-mcp-tools-reference) · [❓ FAQ](#-faq)\n\n---\n\n## 🎯 What is Cortex?\n\nCortex 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.\n\n<table>\n<tr>\n<td width=\"50%\">\n\n### ❌ Without Cortex\n\n```\nYou: \"Add payment processing\"\n\nClaude Code:\n  → Reads CLAUDE.md (if exists)\n  → Reads README.md\n  → Maybe searches some files\n  → Picks random agents (unpredictable)\n  → Misses your PaymentService\n  → Creates duplicate from scratch\n```\n\n</td>\n<td width=\"50%\">\n\n### ✅ With Cortex\n\n```\nYou: \"Add payment processing\"\n\nClaude Code:\n  → Reads CLAUDE.md (finds Cortex instructions)\n  → Loads Cortex memory agent\n  → Queries MCP: \"payment processing\"\n  → Gets: PaymentService, StripeClient, docs\n  → Extends YOUR existing code\n```\n\n</td>\n</tr>\n</table>\n\n---\n\n## 👥 Who Needs Cortex?\n\n| You should use Cortex if... | Why it helps |\n|----------------------------|--------------|\n| 🏢 Your codebase has **20+ files** | AI can't hold everything in context |\n| 🔄 You've had AI **rewrite existing code** | Cortex finds it first |\n| 📚 You have **docs AI keeps ignoring** | Semantic search surfaces them |\n| 🤝 Your team has **established patterns** | AI learns and follows them |\n| 💸 You want **free, local, private** | No cloud, no API costs |\n\n---\n\n## ⚡ How It Works\n\n```mermaid\nflowchart TB\n    subgraph INPUT[\"📁 Your Codebase\"]\n        A1[src/services/payment.ts]\n        A2[src/utils/logger.ts]\n        A3[docs/API.md]\n        A4[README.md]\n    end\n\n    subgraph CORTEX[\"🧠 Cortex Processing\"]\n        B1[📄 Chunk Files]\n        B2[🔢 Generate Embeddings]\n        B3[(🗄️ Vector Database)]\n    end\n\n    subgraph QUERY[\"🤖 AI Assistant\"]\n        C1[\"User: Add email notifications\"]\n        C2[🔍 cortex_query]\n        C3[📋 Results]\n        C4[✅ Writes Code]\n    end\n\n    A1 & A2 & A3 & A4 --> B1\n    B1 --> B2\n    B2 --> B3\n\n    C1 --> C2\n    C2 -->|\"search: notification\"| B3\n    B3 -->|\"Found: NotificationService, EmailClient, logging patterns\"| C3\n    C3 --> C4\n```\n\n| Step | What Happens |\n|:----:|--------------|\n| **1️⃣ Index** | Cortex chunks your code into ~1024 char pieces and creates semantic embeddings |\n| **2️⃣ Query** | AI asks natural language questions: \"how do we handle notifications?\" |\n| **3️⃣ Build** | AI receives relevant files and patterns, writes consistent code |\n\n---\n\n## 🚀 Quick Start\n\n### Step 1 · Add Cortex\n\n```bash\ncd your-project\ngit submodule add https://github.com/Remskill/Cortex.git cortex\ncd cortex && cp .env.example .env && npm install\n```\n\n### Step 2 · Configure Ignore Patterns\n\n> ⚠️ **Do this BEFORE syncing!** Skips junk to be added to your memory.\n\n```bash\ncp docs/.cortexignore.default ../.cortexignore\n```\n\n### Step 3 · Start Services\n\n```bash\ndocker-compose up -d\n```\nWait for model to be ready\n![img.png](docs/img/model.png)\n\n> ⏱️ First run downloads the embedding model (~274MB, 2-5 min)\n\n### Step 4 · Initialize\n\n```bash\nnpm run setup\n```\n\n### Step 5 · Configure MCP\n\nCreate `.mcp.json` in your **project root**:\n\n```json\n{\n  \"mcpServers\": {\n    \"cortex\": {\n      \"command\": \"npx\",\n      \"args\": [\"tsx\", \"cortex/src/server.ts\"],\n      \"env\": {\n        \"DATABASE_URL\": \"postgres://cortex:cortex-dev-pass-123@localhost:5433/cortex\",\n        \"OLLAMA_URL\": \"http://localhost:11434\"\n      }\n    }\n  }\n}\n```\n\n### Step 6 · Restart Claude Code\n\nRun `/exit` and reopen. Verify with `/mcp` → should see `cortex: connected`\n\n![MCP Connected](docs/img/mpc.png)\n\n### Step 7 · Install Git Hook\n\n> 🔴 **Required** — keeps AI memory in sync with your code\n\n```bash\nnpm run hook:install\n```\n\n### Step 8 · Create Cortex Memory Agent (Recommended)\n\n> 💡 **Why?** Agents ensure Claude Code automatically queries Cortex before implementing features.\n\n**Option A: Using Claude Code CLI** (recommended)\n```bash\n/agents\n# → Select \"Create new agent\"\n# → Follow prompts to create an agent for searching codebase patterns\n# → Name it something like \"cortex-memory-agent\"\n```\n\n**Option B: Copy example agent**\n```bash\n# Copy the pre-built agent definition\ncp cortex/docs/cortex-memory-agent.md .claude/agents/cortex-memory-agent.md\n```\n\nSee [`docs/cortex-memory-agent.md`](docs/cortex-memory-agent.md) for a complete agent example.\n\n### Step 9 · Add to CLAUDE.md\n\nTell Claude cli to always use your Cortex agent:\n\n```markdown\n## Cortex Memory\n**ALWAYS use the cortex-memory-agent before implementing ANY feature.**\nThis agent will query Cortex to find existing patterns and prevent code duplication.\n\nManual query example:\ncortex_query(\"what you're building\")\n```\n\n### ✅ Done!\n\n```typescript\ncortex_query(\"how we handle API errors\")\ncortex_query(\"existing notification system\")\ncortex_query(\"database connection patterns\")\n```\n\n---\n\n## 🔄 Git Auto-Sync\n\nAfter installing the hook, Cortex syncs automatically on every commit:\n\n```bash\ngit commit -m \"Add new feature\"\n# 🔄 Syncing changed files...\n# ✅ src/feature.ts (12 chunks)\n# ✅ docs/FEATURE.md (5 chunks)\n```\n\n| Benefit | Description |\n|---------|-------------|\n| 🤖 **Zero effort** | Happens automatically |\n| ⚡ **Incremental** | Only changed files |\n| 🎯 **Always fresh** | AI never sees stale code |\n\n---\n\n## 🛠️ MCP Tools Reference\n\n| Tool | Purpose |\n|------|---------|\n| `cortex_query` | Search by meaning |\n| `cortex_sync` | Manual file sync |\n| `cortex_stats` | Database stats |\n| `cortex_init` | Health check |\n| `cortex_list_files` | List indexed files |\n| `cortex_delete` | Remove from index |\n\n### Query Examples\n\n```typescript\n// Find existing implementations\ncortex_query(\"payment processing\")\ncortex_query(\"user session management\")\n\n// Find patterns\ncortex_query(\"how we handle errors in API routes\")\ncortex_query(\"state management approach\")\n\n// Find documentation\ncortex_query(\"deployment process\")\ncortex_query(\"environment configuration\")\n```\n\n> 💡 **Tip**: Be specific. `\"how we validate user input in forms\"` beats `\"validation\"`.\n\n---\n\n## 📁 Configuration\n\n### .cortexignore\n\nControls what gets indexed. Copy the default:\n\n```bash\ncp cortex/docs/.cortexignore.default .cortexignore\n```\n\n**Auto-excluded**: `node_modules`, `dist`, `build`, `.git`, binary files\n\n### .cortexconfig.json (Optional)\n\n```json\n{\n  \"maxFileSize\": 52428800\n}\n```\n\n> 52428800 = 50MB. Also accepts `\"50MB\"` string format.\n\n---\n\n## 💻 System Requirements\n\n| Component | Minimum |\n|-----------|---------|\n| Docker | Docker Desktop or Engine |\n| RAM | 4GB (8GB recommended) |\n| Disk | ~2GB for models |\n| Node.js | v18+ |\n\n---\n\n## 🔧 Troubleshooting\n\n<details>\n<summary><strong>Services won't start</strong></summary>\n\n```bash\ndocker ps                    # Is Docker running?\ndocker-compose logs          # Check errors\ndocker-compose down && docker-compose up -d\n```\n</details>\n\n<details>\n<summary><strong>No results from queries</strong></summary>\n\n```typescript\ncortex_stats()      // Check if data exists\ncortex_list_files() // List what's indexed\n```\n\nIf empty, run `npm run db:sync`\n</details>\n\n<details>\n<summary><strong>Emergency reset</strong></summary>\n\n```bash\ndocker-compose down -v   # Delete all data\ndocker-compose up -d     # Fresh start\nnpm run setup            # Reinitialize\n```\n</details>\n\n---\n\n## ❓ FAQ\n\n<details>\n<summary><strong>Is it really free?</strong></summary>\n\nYes. MIT licensed, no API costs, no subscriptions. Embeddings run locally via Ollama.\n</details>\n\n<details>\n<summary><strong>Does my code leave my machine?</strong></summary>\n\nNo. Everything runs in local Docker containers. Your code never leaves localhost.\n</details>\n\n<details>\n<summary><strong>What languages work?</strong></summary>\n\nAll of them. Cortex indexes text content — TypeScript, Python, Go, Rust, Java, C++, Markdown, everything.\n</details>\n\n<details>\n<summary><strong>How is this different from grep?</strong></summary>\n\nGrep finds exact text matches. Cortex finds **meaning**:\n\n- Search `\"user authentication\"` → finds login handlers, JWT code, session management\n- Even if none of those files contain the words \"user authentication\"\n</details>\n\n---\n\n## 🤝 Contributing\n\nAll contributions welcome:\n\n- 🐛 Bug reports\n- 💡 Feature ideas & suggestions\n- 📝 Documentation improvements\n- 🔧 Code contributions\n\n**Have an idea?** Open a [GitHub Issue](https://github.com/Remskill/Cortex/issues) — we discuss everything!\n\nFork → Branch → PR → We'll review and merge together.\n\n---\n\n## 🔍 Similar Projects\n\nIf Cortex isn't the right fit, check out **[Zep](https://www.getzep.com/)** — 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!\n\n---\n\n## 💖 Support\n\n<a href=\"https://buymeacoffee.com/denys_medvediev\">\n  <img src=\"https://img.shields.io/badge/☕-Buy%20Me%20a%20Coffee-yellow.svg?style=for-the-badge\" alt=\"Buy Me a Coffee\">\n</a>\n\n---\n\n## 🔗 Links\n\n[GitHub](https://github.com/Remskill/Cortex) · [Issues](https://github.com/Remskill/Cortex/issues) · [LinkedIn](https://www.linkedin.com/in/denysmedvediev/)\n\n---\n\n<div align=\"center\">\n\n**Made with ❤️ by [Denys Medvediev](https://buymeacoffee.com/denys_medvediev)**\n\n⭐ **Star this repo if it helps you!** ⭐\n\n</div>\n"}