{"id":"a13854fc-69bf-42ce-b29d-60a840cec8c1","slug":"cortexai-memory-cortex","kind":"mcp","name":"cortex","summary":"Persistent memory for AI coding assistants Every AI coding tool forgets everything between sessions. Cortex fixes that.","owner":"cortexai-memory","repoUrl":"https://github.com/cortexai-memory/cortex","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-02-07T10:27:38.000Z","addedAt":"2026-10-21T20:34:57.586Z","logoUrl":"https://avatars.githubusercontent.com/u/260043439?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["memory-knowledge"],"tags":[],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-27T23:11:08.482Z","sample":false,"url":"https://conduits.dev/tools/cortexai-memory-cortex","language":"Python","transports":["stdio"],"install":{"pypi":"cortex-memory"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"\n\n# Cortex\n\n**Persistent memory for AI coding assistants**\n\nEvery AI coding tool forgets everything between sessions. Cortex fixes that.\n\n[](LICENSE)\n[](https://github.com/cortexai-memory/cortex/actions)\n[](https://www.apple.com/macos/)\n[](https://www.linux.org/)\n\n[Install](#install) · [How It Works](#how-it-works) · [Usage](#usage) · [Config](#configuration) · [FAQ](#faq)\n\n
\n\n---\n\n## The Problem\n\nEvery AI coding assistant — Claude Code, Cursor, Copilot, Aider — starts each session with **zero memory** of what happened before.\n\n**You waste 10-15 minutes every session:**\n- \"What was I working on?\"\n- \"Why did I make that architectural decision?\"\n- \"Which files did I change yesterday?\"\n\n**This costs you ~5 hours per week.**\n\n\n\n\n## The Fix\n\nCortex gives your AI **permanent memory**. One command, zero configuration.\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/cortexai-memory/cortex/main/install.sh | bash\ncd your-project && cx # That's it. AI now remembers everything.\n```\n\n\n\n\n**How it works:**\n```\ngit commit → Cortex captures metadata → AI reads context → Zero re-explaining\n```\n\n**Two layers:**\n- **Layer 0 (bash):** Core memory. No dependencies. Works in 30 seconds.\n- **Layer 1 (Python MCP):** AI superpowers. Semantic search. Impact analysis. Knowledge base.\n\n## Quick Start\n\n### I want memory NOW (30 seconds)\n\n```bash\n# One command\ncurl -fsSL https://raw.githubusercontent.com/cortexai-memory/cortex/main/install.sh | bash\nsource ~/.zshrc # or ~/.bashrc\n\n# Use it\ncd your-project\ncx # Instead of 'claude' - now with memory\n```\n\n**Done.** Claude now sees your recent commits, active files, and session history.\n\n**[See detailed quickstart →](QUICKSTART.md)**\n\n### I want AI superpowers (5 minutes)\n\nSemantic search, knowledge base, impact analysis:\n\n```bash\n# Automated setup (installs Ollama, models, everything)\ncd cortex\n./setup-mcp.sh # Takes 5 minutes, fully automated\n\n# Test it\ncx\n# You: \"Find authentication bugs\"\n# Claude: [Semantic search finds relevant commits]\n# You: \"What breaks if I change auth/login.py?\"\n# Claude: [Shows full dependency tree]\n```\n\n**[See examples →](EXAMPLES.md)**\n\n## Why Cortex?\n\n| Without Cortex | With Cortex |\n|----------------|-------------|\n| 😤 Re-explain project every session (10 min) | 😊 AI knows everything (0 sec) |\n| 🔍 `git grep` through 200 commits (10+ min) | ⚡ Natural language search (10 sec) |\n| 🤷 \"Why did we choose MongoDB?\" → Unknown | 💡 Instant recall of all decisions |\n| 😱 Change file → hope nothing breaks (30+ min) | 🎯 Full dependency tree (5 sec) |\n| **~5 hours wasted per week** | **~5 minutes wasted per week** |\n\n**Time saved: 260 hours/year = 6.5 weeks of productivity**\n\n\n\n\n## Install\n\n### Option 1: Fast Install (Recommended)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/cortexai-memory/cortex/main/install.sh | bash\nsource ~/.zshrc # or ~/.bashrc\n```\n\n### Option 2: Manual Clone\n\n```bash\ngit clone https://github.com/cortexai-memory/cortex.git\ncd cortex && ./install.sh\nsource ~/.zshrc\n```\n\n**Requirements:** git, jq (both pre-installed on macOS)\n\n### MCP Server (Optional - for Claude Code)\n\n**One command, fully automated setup:**\n\n```bash\ncd cortex\n./setup-mcp.sh # Installs Ollama, models, Python, everything (5 minutes)\n```\n\n**That's it.** The script automatically:\n- ✅ Installs Ollama (if not installed)\n- ✅ Starts Ollama service\n- ✅ Pulls nomic-embed-text model (274 MB)\n- ✅ Installs uv + Python dependencies\n- ✅ Registers MCP server with Claude Code\n- ✅ Tests everything works\n\n**Manual setup** (if you prefer):\n\n```bash\n# 1. Install dependencies\nbrew install ollama # macOS\ncd cortex && uv sync\n\n# 2. Pull model\nollama serve &\nollama pull nomic-embed-text\n\n# 3. Register with Claude Code (auto-created by setup-mcp.sh)\n# .mcp.json file will be in cortex directory\n```\n\n**MCP Tools Available (9 total):**\n\n**Phase 2 - Context & Search:**\n- `cortex_context` - Live session context (equivalent to SESSION_CONTEXT.md)\n- `cortex_search` - **Semantic search** over commits (natural language queries!)\n- `cortex_diff` - Compare commits with detailed diffs\n- `cortex_index` - Index commits for vector search\n- `cortex_status` - Memory stats and configuration\n- `cortex_file_history` - Git history for specific files\n\n**Phase 3 - Knowledge Base:**\n- `cortex_remember` - Store decisions, lessons, patterns, bug fixes\n- `cortex_recall` - Search knowledge base with full-text search\n- `cortex_decisions` - List all architectural decisions\n\n**Phase 4 - Code Intelligence:**\n- `cortex_impact` - **Impact analysis** - \"what breaks if I change this file?\"\n- `cortex_related` - Find related files (imports, co-changes)\n- `cortex_patterns` - Detect hotspots, modules, and development cycles\n\n**Example searches:**\n- \"authentication bugs\" → finds auth-related commits by meaning, not keywords\n- \"recent refactorings\" → semantic understanding of refactor commits\n- \"database schema changes\" → finds relevant migrations\n\n**Quick Start (MCP Server):**\n```bash\n# PHASE 2: Semantic Search\ncortex_index() # Index commits for semantic search\ncortex_search(query=\"authentication bugs\")\ncortex_search(query=\"database migrations\", file_type=\"sql\")\n\n# PHASE 3: Knowledge Base\ncortex_remember(\n category=\"decision\",\n title=\"Use PostgreSQL\",\n content=\"Chose PostgreSQL for JSONB support and full-text search\"\n)\ncortex_recall(query=\"database choice\")\ncortex_decisions() # List all decisions\n\n# PHASE 4: Code Intelligence\ncortex_impact(filepath=\"src/auth/login.py\") # What breaks if I change this?\ncortex_related(filepath=\"src/auth/login.py\") # Find related files\ncortex_patterns() # Detect hotspots and patterns\n```\n\n## Usage\n\n### Starting an AI Session\n\n```bash\ncd your-project\ncx # instead of 'claude'\n```\n\nThat's it. First run auto-initializes. Every run after that generates fresh context.\n\n### Checking Status\n\n```bash\ncortex-status.sh # View project memory status\n```\n\nShows:\n- Recent commits and activity\n- Memory usage (tracked commits, sessions, storage)\n- Current task (from PROJECT_STATE.md or features.json)\n- Health status\n- JSON output available with `--json` flag\n\n### File Watching (Optional)\n\n```bash\ncortex-watch.sh [--daemon] # Monitor file changes in real-time\n```\n\nAutomatically tracks file system events (create, modify, delete) to `.cortex/events.jsonl`. Requires `fswatch` (macOS) or `inotify-tools` (Linux).\n\n### Progress Tracking\n\nCortex auto-generates `PROGRESS.md` showing:\n- ✅ What's been done (last 7 days)\n- 🔨 What's in progress (feature branches)\n- ⏳ What's next (from PROJECT_STATE.md)\n- 📊 Velocity metrics (commits/day, lines added)\n\n### Session Memory (NEW in v1.7.0)\n\n**Work without committing!** Cortex now remembers your session even if you don't commit:\n\n```bash\ncx\n# Chat for 10 min, make changes\n# Close terminal without committing\n\n# Later...\ncx\n# ✅ Claude sees your previous uncommitted work!\n```\n\n**Snapshot Management:**\n```bash\ncortex-snapshot.sh list # See all snapshots\ncortex-snapshot.sh show latest # View details\ncortex-snapshot.sh clear 7 # Remove snapshots older than 7 days\n```\n\n**How it works:**\n- On `cx` exit, Cortex auto-saves uncommitted work\n- Next session shows: \"PREVIOUS SESSION (uncommitted work)\"\n- You can continue working OR commit\n- No more re-explaining what you did!\n\n### Enhanced Workflow (NEW in v1.8.0)\n\n**Quick Commit:**\n```bash\ncx-commit \"feat: add login page\" # Commit + enrich + update context\ncx-commit \"fix: auth bug\" src/auth.js # Commit specific files\n```\n\n**Session Notes:**\n```bash\ncx-note add \"Remember to test edge cases\" # Add note\ncx-note list # View all notes\ncx-note export # Export to SESSION_NOTES.md\n```\n\n**Snapshot Power Tools:**\n```bash\ncortex-snapshot.sh diff latest # View snapshot diff\ncortex-snapshot.sh search \"authentication\" # Search snapshots\ncortex-snapshot.sh branch latest new-feature # Create branch from snapshot\ncortex-snapshot.sh undo # Remove latest snapshot\n```\n\n**Preview Context:**\n```bash\ncortex-preview.sh # See what Claude will receive (without launching)\n```\n\n### Smart Features (v1.8.0)\n\n- **Auto-restore**: Prompts you to continue from previous session on `cx` start\n- **Session summaries**: AI summary of what you accomplished (when CORTEX_ENRICH=1)\n- **Context prioritization**: Cortex highlights most-changed files automatically\n- **Focus areas**: Shows which file types you're actively working on\n\n## What Your AI Sees\n\nWhen you run `cx`, Cortex generates `SESSION_CONTEXT.md`:\n\n```markdown\n# SESSION_CONTEXT.md (auto-generated by Cortex)\n# Session #42 | Project: my-saas-app\n\n## SINCE LAST SESSION\na1b2c3d feat(auth): add Google OAuth provider\ne4f5g6h test(auth): add login flow E2E tests\n\n## RECENT COMMITS (24h)\n- a1b2c3d feat(auth): add Google OAuth provider [+145/-2]\n- e4f5g6h test(auth): add login flow E2E tests [+89/-0]\n- f7g8h9i fix(auth): handle OAuth callback redirect [+12/-4]\n\n## CURRENT TASK\nFeature F006: Metadata Writer — Status: pending\n\n## GIT STATUS\nBranch: feature/auth | Uncommitted: 2 files\nLast: f7g8h9i fix(auth): handle OAuth callback redirect (35 minutes ago)\n\n## WARNINGS\nNone.\n```\n\nYour AI assistant reads this automatically. No copy-pasting. No re-explaining.\n\n## How It Works\n\n**Two-layer architecture:**\n\n```\n┌──────────────────────────────────────────────────────────────────────┐\n│ HOW CORTEX WORKS │\n├──────────────────────────────────────────────────────────────────────┤\n│ │\n│ LAYER 0 (Bash) — Core Memory │\n│ ───────────────────────────────── │\n│ 1. GIT HOOK (post-commit) │\n│ Captures commit metadata to .cortex/commits.jsonl │\n│ Runs in <10ms. Never blocks git. │\n│ │\n│ 2. CONTEXT GENERATOR (cortex-context.sh) │\n│ Reads git data → writes SESSION_CONTEXT.md │\n│ Runs in <100ms. ~500 tokens of context. │\n│ │\n│ 3. SESSION MANAGER (cx command) │\n│ Generate context → launch Claude → log session │\n│ Auto-initializes on first run per project. │\n│ │\n│ LAYER 1 (Python MCP) — Intelligence [Optional] │\n│ ─────────────────────────────────────────── │\n│ 4. PHASE 2: Semantic Search │\n│ • LanceDB vectors (.cortex/vectors/) — 768-dim embeddings │\n│ • Ollama (nomic-embed-text) — local, offline │\n│ • Tools: cortex_search, cortex_index, cortex_diff │\n│ │\n│ 5. PHASE 3: Knowledge Base │\n│ • SQLite + FTS5 (.cortex/knowledge.db) — full-text search │\n│ • Stores: decisions, lessons, patterns, bug fixes │\n│ • Tools: cortex_remember, cortex_recall, cortex_decisions │\n│ │\n│ 6. PHASE 4: Code Intelligence │\n│ • SQLite graph (.cortex/graph.db) — file relationships │\n│ • Tracks: imports, co-changes, dependencies │\n│ • Tools: cortex_impact, cortex_related, cortex_patterns │\n│ │\n│ 7. MCP SERVER │\n│ Exposes 12 tools to Claude Code via Model Context Protocol │\n│ │\n└──────────────────────────────────────────────────────────────────────┘\n```\n\n### Storage\n\nAll data lives in `.cortex/` (auto-added to `.gitignore`):\n\n```\n.cortex/\n├── commits.jsonl # Commit metadata (one JSON line per commit)\n├── sessions.jsonl # Session start/end timestamps\n├── summaries/ # Optional LLM-generated summaries\n│ └── latest.md\n├── vectors/ # Vector embeddings (Phase 2)\n│ └── commits.lance # LanceDB storage for semantic search\n├── knowledge.db # Knowledge base (Phase 3)\n│ # SQLite + FTS5: decisions, lessons, patterns, bug fixes\n└── graph.db # File relationship graph (Phase 4)\n # SQLite adjacency list: imports, co-changes, dependencies\n```\n\n## Configuration\n\n### Layer 0 (Bash)\n\nEdit `~/.cortex/config`:\n\n```ini\n# LLM provider for richer summaries (optional)\n# Options: none | ollama | openrouter | gemini\nllm_provider=none\nllm_model=qwen2.5-coder:7b\n\n# Uncomment to use cloud providers\n# openrouter_key=sk-or-...\n# gemini_key=AI...\n```\n\nEnable LLM enrichment for AI-powered commit summaries:\n\n```bash\nexport CORTEX_ENRICH=1\n```\n\n### Layer 1 (Python MCP)\n\nMCP server configuration is in `.mcp.json` (auto-created during setup):\n\n```json\n{\n \"mcpServers\": {\n \"cortex-memory\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"--directory\", \"/path/to/cortex\", \"cortex-memory\"]\n }\n }\n}\n```\n\n**Python dependencies:** Managed by `uv` (see `pyproject.toml`)\n- `mcp[cli]>=1.0.0` - MCP protocol server\n- `pydantic>=2.0.0` - Data validation\n- `lancedb>=0.6.0` - Vector database (optional, for semantic search)\n- `ollama>=0.1.0` - Local embeddings (optional, for semantic search)\n- `numpy>=1.24.0` - Vector operations (optional, for semantic search)\n\n## Works With\n\n| Tool | Status | How |\n|------|--------|-----|\n| Claude Code | Works | Reads SESSION_CONTEXT.md automatically |\n| Cursor | Works | Add SESSION_CONTEXT.md to .cursorrules |\n| Aider | Works | Reads markdown files from project root |\n| Continue.dev | Works | Configure in .continue/ |\n| Copilot | Works | Reference in prompts |\n| Any AI tool | Works | Any tool that reads project files |\n\n## Benchmarks\n\n| Operation | Time | Impact |\n|-----------|------|--------|\n| Post-commit hook | <10ms | Never blocks git |\n| Context generation | <100ms | Instant on `cx` |\n| Memory usage | <5MB | Negligible |\n| Context size | ~500 tokens | <1% of context window |\n\n## Health Check\n\n```bash\n~/.cortex/bin/cortex-doctor.sh\n```\n\n```\nCortex Doctor v0.1.0\n────────────────────────\n✓ git 2.43.0\n✓ jq 1.7.1\n✓ ~/.cortex/ exists\n✓ Scripts executable\n✓ cx alias configured\n✓ .cortex/ initialized\n✓ Git hook installed (v1)\n✓ commits.jsonl valid (42 entries)\n✓ sessions.jsonl valid (12 sessions)\n○ Ollama: not configured (optional)\n\nHealth: GOOD (9/9 required checks passed)\n```\n\n## FAQ\n\n**Does it slow down git?**\nNo. The post-commit hook runs in <10ms and never blocks. It uses `exit 0` to ensure git is never affected.\n\n**Does it need Ollama/LLMs?**\nNo. Layer 0 (bash) works with just git + jq. Layer 1 (MCP server with semantic search) is optional and requires Ollama for embeddings.\n\n**Do I need the MCP server?**\nNo. The MCP server (Layer 1) is optional. Layer 0 provides full functionality via SESSION_CONTEXT.md. Layer 1 adds semantic search and Claude Code integration.\n\n**What's the difference between Layer 0 and Layer 1?**\n- **Layer 0 (bash):** Captures commits → generates SESSION_CONTEXT.md. No Python, no dependencies, always works.\n- **Layer 1 (Python MCP):** Semantic search over commits, natural language queries, Claude Code integration. Optional.\n\n**Does it work in CI/CD?**\nYes. The hook auto-detects CI environments (GitHub Actions, GitLab CI, Jenkins, Buildkite, CircleCI, Travis) and skips itself.\n\n**Does it work with teams?**\nYes. `.cortex/` is local-only (auto-added to .gitignore). Each developer has their own memory. No merge conflicts.\n\n**How much disk space do vector embeddings use?**\nApproximately 3KB per commit. 1000 commits ≈ 3MB. LanceDB storage is efficient and local.\n\n**Can I use semantic search without Ollama?**\nNot yet. Currently requires local Ollama for embeddings. Cloud embedding providers (OpenAI, Cohere) planned for future releases.\n\n**How do I uninstall?**\n```bash\n./install.sh --uninstall\n# or manually: rm -rf ~/.cortex && remove 'cx' alias from shell rc\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\n[MIT](LICENSE) — free for personal and commercial use.\n\n---\n\n\nNever re-explain your project to an AI again.\n
\n"}