cortex-mcp 2.8.0 → 3.0.0

package/README.md

@@ -1,227 +1,394 @@
-# 🧠 Cortex MCP — Persistent Memory for AI Coding Assistants
-
-> **Give your AI a brain that never forgets.**  
-> Cortex injects context from every past session directly into your AI's LLM requests — automatically.
-
-[![npm](https://img.shields.io/npm/v/cortex-mcp)](https://www.npmjs.com/package/cortex-mcp)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-[![100% Free](https://img.shields.io/badge/price-100%25%20FREE-brightgreen)](https://www.npmjs.com/package/cortex-mcp)
-
----
-
-## What Is Cortex?
-
-Every time you close your IDE, your AI forgets everything. Every decision, every bug fix, every convention — gone.
-
-**Cortex solves this.** It's a local MCP server that:
-- Stores everything your AI learns about your project
-- Automatically injects the right memories into every conversation
-- Learns passively by reading your AI's own responses
-- Never needs an API key, never phones home, never loses your data
-
-**Fully local. Fully free. No account. No limits.**
-
----
-
-## Quick Start (30 seconds)
-
-```bash
-# Install globally
-npm install -g cortex-mcp
-
-# Auto-configure your AI client (Cursor, Claude, Windsurf, Copilot...)
-cd your-project
-cortex-setup
-```
-
-That's it. Restart your AI client and Cortex is active.
-
----
-
-## Supported AI Clients
-
-| Client | Auto-configured by `cortex-setup` |
-|--------|----------------------------------|
-| **Cursor** | ✅ |
-| **Claude Desktop** | ✅ |
-| **GitHub Copilot (VS Code)** | ✅ |
-| **Windsurf** | ✅ |
-| **Zed** | ✅ |
-| **Antigravity / Gemini** | ✅ |
-| Any MCP-compatible client | ✅ Manual config |
-
----
-
-## How It Works
-
-```
-Your AI responds → Cortex reads the response → Extracts decisions, corrections, bug fixes
-                                                       ↓
-Next conversation → Cortex injects relevant memories → AI already knows your project
-```
-
-**No manual work required.** Every session builds the brain automatically.
-
----
-
-## All 30 Tools (All Free)
-
-### Core Memory
-| Tool | What it does |
-|------|-------------|
-| `store_memory` | Store a decision, correction, convention, or bug fix |
-| `recall_memory` | Search memories by topic, file, or type |
-| `force_recall` | At session start — returns ALL critical context + topic search |
-| `auto_learn` | After every AI reply — auto-extracts memories from text |
-| `quick_store` | One-line shortcut for fast memory storage |
-
-### Memory Management
-| Tool | What it does |
-|------|-------------|
-| `list_memories` | List all active memories, filterable by type |
-| `update_memory` | Edit an existing memory |
-| `delete_memory` | Remove a memory permanently |
-| `pin_memory` | Pin a memory so it's ALWAYS injected (for critical rules) |
-| `unpin_memory` | Unpin a previously pinned memory |
-| `undo_last` | Undo the last N stored memories |
-| `clear_memories` | Bulk delete by type or age |
-| `thumbs_up` | Mark a memory as useful (boosts importance) |
-| `thumbs_down` | Mark a memory as wrong (demotes/removes it) |
-| `get_related_memories` | Follow graph edges to find connected memories |
-
-### Time & History
-| Tool | What it does |
-|------|-------------|
-| `search_timeline` | Search memories by date range ("what did we decide last week?") |
-| `get_daily_summary` | Read or generate a summary of today's/any day's memories |
-
-### Project Intelligence
-| Tool | What it does |
-|------|-------------|
-| `scan_project` | Scan source code and auto-create memories from comments & structure |
-| `get_context` | Get full brain context for the current file/topic |
-| `get_stats` | Stats about the brain (memory count, types, health) |
-| `analytics` | Deep analytics — distribution, most accessed, feedback scores |
-
-### Code Safety (Anti-Hallucination)
-| Tool | What it does |
-|------|-------------|
-| `verify_code` | Checks if packages exist in package.json before suggesting imports |
-| `verify_files` | Confirms file paths are real before referencing them |
-| `search_by_file` | Find all memories related to a specific file |
-
-### Backup & Portability
-| Tool | What it does |
-|------|-------------|
-| `backup_brain` | Creates a timestamped `.db` copy of the entire memory database |
-| `export_memories` | Export all memories to a shareable JSON file |
-| `import_memories` | Import memories from a JSON file (skip duplicates) |
-
-### Health & Maintenance
-| Tool | What it does |
-|------|-------------|
-| `health_check` | Server health, embedding status, vector search status |
-| `repair_brain` | Rebuild FTS index, integrity check, VACUUM, fix orphaned data |
-| `detect_conflicts` | Find contradictory memories (e.g. "use X" vs "avoid X") |
-| `suggest_cleanup` | Identify stale low-value memories you should delete |
-
----
-
-## Memory Types
-
-Cortex organizes everything into 5 types:
-
-| Type | What gets stored | Auto-detected from |
-|------|-----------------|-------------------|
-| `correction` | "Don't do X", "Wrong approach was Y" | Words like "never", "don't use", "avoid" |
-| `decision` | "We chose X over Y because Z" | "We decided", "going with", "chosen" |
-| `convention` | "Always use X for Y in this project" | "always", "must", "convention", "standard" |
-| `bug_fix` | "Bug was X, fixed by Y" | "root cause", "fixed by", "was crashing" |
-| `insight` | "Key thing to know: X" | "important", "worth noting", "key insight" |
-
-Plus 4 additional auto-detected types: `failed_attempt`, `business_rule`, `gotcha`, `current_task`
-
----
-
-## Web Dashboard
-
-When Cortex is running, open **http://localhost:3456** to:
-- View all memories organized by type
-- Search and filter in real-time
-- Delete or pin memories from the UI
-- Export your brain as JSON
-- See live stats (auto-refreshes every 30 seconds)
-
----
-
-## Git Integration
-
-`cortex-setup` automatically installs git hooks that capture:
-- Every commit (type + message + files changed)
-- Every branch switch
-- Every merge
-
-So your AI knows your recent git history automatically.
-
----
-
-## Environment Variables
-
-```bash
-CORTEX_PORT=4000            # Dashboard port (default: 3456)
-CORTEX_DEBUG=1              # Enable file logging (cortex.log)
-CORTEX_MAX_CONTEXT_CHARS=12000  # Context size injected per request (default: 12000)
-OPENAI_API_KEY=sk-...       # Enable LLM-enhanced memory classification
-ANTHROPIC_API_KEY=sk-ant-..  # Alternative LLM provider (Claude)
-CORTEX_LLM_BASE_URL=http://localhost:11434  # Ollama or any OpenAI-compatible API
-```
-
----
-
-## Data & Privacy
-
-- **100% local.** All memories stored in `.ai/brain-data/` inside your project folder.
-- **Zero telemetry.** No analytics, no phone-home, no account required.
-- **Offline-first.** Works with no internet. LLM key optional (uses fast regex-based classification otherwise).
-- **Open source.** MIT license.
-
----
-
-## Manual Configuration
-
-If `cortex-setup` doesn't detect your client, add this to your MCP config:
-
-```json
-{
-  "mcpServers": {
-    "cortex": {
-      "command": "npx",
-      "args": ["-y", "cortex-mcp"]
-    }
-  }
-}
-```
-
----
-
-## Limits (Auto-Reset Every 24 Hours)
-
-| Operation | Daily Limit |
-|-----------|------------|
-| Store memory | 500/day |
-| Auto-learn calls | 1,000/day |
-| Total tool calls | 5,000/day |
-
-All limits reset automatically every 24 hours. No manual restart needed.
-
----
-
-## Built By
-
-**Perla Jaswanth Kumar** — [GitHub](https://github.com/jaswanthkumarj1234-beep/cortex-mcp)  
-Website: [cortex-website-theta.vercel.app](https://cortex-website-theta.vercel.app)  
-Issues: [GitHub Issues](https://github.com/jaswanthkumarj1234-beep/cortex-mcp/issues)
-
----
-
-*Cortex is 100% free and open source. Give your AI a brain. It's about time.*
+# Cortex MCP — Persistent AI Memory
+
+[![npm version](https://img.shields.io/npm/v/cortex-mcp.svg)](https://www.npmjs.com/package/cortex-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/cortex-mcp.svg)](https://www.npmjs.com/package/cortex-mcp)
+[![CI](https://github.com/jaswanthkumarj1234-beep/cortex-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/jaswanthkumarj1234-beep/cortex-mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org/)
+
+> Give your AI coding assistant a brain that remembers across sessions.
+
+Cortex is an MCP (Model Context Protocol) server that provides persistent, intelligent memory to any AI coding assistant — Cursor, Claude Code, Windsurf, Cline, or any MCP-compatible tool.
+
+## What's New in v2.6 — OpenClaw-Style Autonomous Brain
+
+- **🧠 SOUL.md** — Persistent AI identity file, auto-learns from your top memories
+- **📓 Daily Diary** — Timestamped Markdown logs of every session's decisions and insights
+- **📄 MEMORY.md** — Human-readable knowledge export, auto-synced with the database
+- **🎯 MMR Re-ranking** — Maximal Marginal Relevance ensures diverse search results (λ=0.7)
+- **⚡ Embedding Cache** — LRU cache (256 entries) skips redundant vector computations
+- **🔍 Query Expansion** — 40+ synonym groups + alternative query generation for zero-result fallback
+- **👤 Access Pattern Tracking** — Learns which memory types you use most, boosts them 0.7x–1.8x
+- **🔗 Cross-Memory Linking** — Auto-links related memories by files, tags, and word overlap
+- **⏳ Two-Tier Decay** — Transactional memories (INSIGHT) decay at 5 days, operational (DECISION/CORRECTION) protected for 60 days
+- **🤖 100% Autonomous** — All features run automatically on download, zero config needed
+
+See [CHANGELOG.md](CHANGELOG.md) for full details.
+
+## The Problem
+
+Every time you start a new conversation, your AI assistant forgets everything:
+
+- Coding conventions you already explained
+- Bugs you already fixed
+- Decisions you already made
+- What files you were working on
+
+**Cortex solves this.** It stores, ranks, and proactively recalls context so your AI never starts from zero.
+
+## Quick Start
+
+### Option 1: npx (recommended — always up to date)
+
+Add to your MCP config (no install needed, auto-updates on every launch):
+
+```json
+{
+    "mcpServers": {
+        "cortex": {
+            "command": "npx",
+            "args": ["-y", "cortex-mcp@latest"],
+            "transportType": "stdio"
+        }
+    }
+}
+```
+
+### 🧠 Supercharge with Free LLM (Optional)
+
+Add a **free** OpenRouter API key to make Cortex 3x smarter at extracting knowledge:
+
+```json
+{
+    "mcpServers": {
+        "cortex": {
+            "command": "npx",
+            "args": ["-y", "cortex-mcp@latest"],
+            "transportType": "stdio",
+            "env": {
+                "OPENROUTER_API_KEY": "sk-or-v1-your-key-here"
+            }
+        }
+    }
+}
+```
+
+**How to get a free key:**
+
+1. Go to [openrouter.ai/keys](https://openrouter.ai/keys)
+2. Create a free account
+3. Generate an API key
+4. Paste it in the config above
+
+**What it enables:** When regex can't extract patterns from your conversation, Cortex uses a free LLM (Llama 4 Scout) to catch implicit decisions, preferences, and architecture knowledge that keywords miss. Without it, ~70% of conversations produce no memories. With it, that drops to ~20%.
+
+### Option 2: Global install
+
+```bash
+npm install -g cortex-mcp
+```
+
+Then add to your MCP config:
+
+```json
+{
+    "mcpServers": {
+        "cortex": {
+            "command": "cortex-mcp",
+            "transportType": "stdio"
+        }
+    }
+}
+```
+
+### Option 2: Clone from source
+
+```bash
+git clone https://github.com/jaswanthkumarj1234-beep/cortex-mcp.git
+cd cognitive-memory
+npm install
+npm run build
+```
+
+Then add to your MCP config:
+
+```json
+{
+    "mcpServers": {
+        "cortex": {
+            "command": "node",
+            "args": ["<path-to>/cognitive-memory/dist/mcp-stdio.js"],
+            "transportType": "stdio"
+        }
+    }
+}
+```
+
+Restart your IDE and Cortex is active.
+
+### Try the Demo
+
+See Cortex in action without any AI client:
+
+```bash
+npm run demo          # Interactive demo — store, search, dedup
+npm run benchmark     # Performance benchmark — write, read, FTS ops/sec
+```
+
+### IDE-Specific Setup Guides
+
+Step-by-step instructions for your IDE: **[Cursor · Claude Code · Windsurf · Cline · Copilot](docs/ide-setup.md)**
+
+### Recipes & Use Cases
+
+10 practical examples: **[docs/recipes.md](docs/recipes.md)** — conventions, bug tracking, anti-hallucination, team onboarding, and more.
+
+## Features
+
+### Why Cortex?
+
+| Feature                     |                          Cortex                          | Other MCP memory servers |
+| --------------------------- | :------------------------------------------------------: | :----------------------: |
+| **Retrieval**               |              Hybrid (FTS + Vector + Graph)               |     Usually FTS only     |
+| **Auto-learning**           |           Extracts memories from AI responses            |    Manual store only     |
+| **Hallucination detection** |              `verify_code` + `verify_files`              |            No            |
+| **Git integration**         |       Auto-captures commits, diffs, branch context       |            No            |
+| **Cognitive features**      | Decay, attention, contradiction detection, consolidation |            No            |
+| **Brain pipeline**          |               12+ layer context injection                | Simple key-value recall  |
+| **Setup**                   |          `npm i -g cortex-mcp` + 1 config line           |          Varies          |
+| **Offline**                 |          100% local SQLite (no API key needed)           |    Often requires API    |
+
+### 20 MCP Tools
+
+| Tool              | Purpose                                                                            |
+| ----------------- | ---------------------------------------------------------------------------------- |
+| `force_recall`    | Full brain dump at conversation start (12+ layer pipeline)                         |
+| `recall_memory`   | Search memories by topic (FTS + vector + graph)                                    |
+| `store_memory`    | Store a decision, correction, convention, or bug fix                               |
+| `quick_store`     | One-liner memory storage with auto-classification                                  |
+| `auto_learn`      | Extract memories from AI responses automatically                                   |
+| `scan_project`    | Scan project structure, stack, git, exports, architecture                          |
+| `verify_code`     | Check if imports/exports/env vars actually exist                                   |
+| `verify_files`    | Check if file paths are real or hallucinated                                       |
+| `get_context`     | Get compressed context for current file                                            |
+| `review_code`     | Review code against stored conventions and past bug patterns                       |
+| `pre_check`       | Pre-flight check before editing — get all conventions and past bugs for a file     |
+| `check_impact`    | Impact analysis — check which files depend on the file you plan to modify          |
+| `resume_work`     | Resume after a break — get last session summary, recent corrections, pending tasks |
+| `get_stats`       | Memory database statistics                                                         |
+| `list_memories`   | List all active memories                                                           |
+| `update_memory`   | Update an existing memory                                                          |
+| `delete_memory`   | Delete a memory                                                                    |
+| `export_memories` | Export all memories to JSON                                                        |
+| `import_memories` | Import memories from JSON                                                          |
+| `health_check`    | Server health check                                                                |
+
+### 14-Layer Brain Pipeline
+
+Every conversation starts with `force_recall`, which runs 14 layers (layers 6-12 run **in parallel** for speed):
+
+| Layer | Feature                                                       | Parallel? |
+| :---: | ------------------------------------------------------------- | :-------: |
+| Soul  | SOUL.md — persistent AI identity and preferences              |     —     |
+|   0   | Session management — track what you're working on             |     —     |
+|  0.5  | Day 1 auto-scan — scan project on first run                   |     —     |
+|   1   | Maintenance — decay, consolidate, soul-learn, MEMORY.md sync  |     —     |
+|   2   | Attention focus — detect debugging vs coding vs reviewing     |     —     |
+|   3   | Session continuity — resume where you left off                |     —     |
+|   4   | Hot corrections — frequently-corrected topics                 |     —     |
+|   5   | Core context — corrections, decisions, conventions, bug fixes |     —     |
+|   6   | Anticipation — proactive recall based on current file         |    ✅     |
+|   7   | Temporal — what changed today, yesterday, this week           |    ✅     |
+|  7.5  | Daily Diary — recent session logs in Markdown                 |    ✅     |
+|   8   | Workspace git — branch, recent commits, diffs                 |    ✅     |
+|  8.5  | Git memory — auto-capture commits + file changes              |    ✅     |
+|   9   | Topic search — FTS + vector + MMR diversity + personal boost  |    ✅     |
+|  10   | Knowledge gaps — flag files with zero memories                |    ✅     |
+|  11   | Export map — all functions/classes (anti-hallucination)       |    ✅     |
+|  12   | Architecture graph — layers, circular deps, API endpoints     |    ✅     |
+
+### Cognitive Features
+
+- **Confidence decay** — old unused memories fade, frequently accessed ones strengthen
+- **Attention ranking** — debugging context boosts bug-fix memories, coding boosts conventions
+- **Contradiction detection** — new memories automatically supersede conflicting old ones
+- **Memory consolidation** — similar memories merge into higher-level insights
+- **Cross-session threading** — related sessions link by topic overlap
+- **Learning rate** — topics corrected 3+ times get CRITICAL priority
+
+### Performance & Reliability
+
+- **`force_recall` latency**: ~3-5s first call, instant on cache hit (v1.2 — was 15-19s)
+- **`recall_memory` latency**: <1ms average (local SQLite + WAL)
+- **Throughput**: 1800+ ops/sec (verified via Soak Test)
+- **Stability**: Zero memory leaks over sustained operation
+- **Protocol**: Full JSON-RPC 2.0 compliance (passed E2E suite)
+- **CI**: Tested on Node 18, 20, 22 with lint + build + E2E on every push
+
+### Anti-Hallucination
+
+- Deep export map scans every source file for all exported functions, classes, types
+- When AI references a function that doesn't exist, `verify_code` suggests the closest real match
+- Architecture graph shows actual project layers and dependencies
+
+## Optional: LLM Enhancement
+
+Cortex works fully without any API key. Optionally, add an LLM key for smarter memory extraction:
+
+```bash
+# Option 1: OpenAI
+set OPENAI_API_KEY=sk-your-key
+
+# Option 2: Anthropic
+set ANTHROPIC_API_KEY=sk-ant-your-key
+
+# Option 3: Local (Ollama, free)
+set CORTEX_LLM_KEY=ollama
+set CORTEX_LLM_BASE_URL=http://localhost:11434
+```
+
+## Memory Types
+
+| Type                | Use For                                             |
+| ------------------- | --------------------------------------------------- |
+| `CORRECTION`        | "Don't use var, use const"                          |
+| `DECISION`          | "We chose PostgreSQL over MongoDB"                  |
+| `CONVENTION`        | "All API routes start with /api/v1"                 |
+| `BUG_FIX`           | "Fixed race condition in auth middleware"           |
+| `INSIGHT`           | "The codebase uses a layered architecture"          |
+| `FAILED_SUGGESTION` | "Tried Redis caching, too complex for this project" |
+| `PROVEN_PATTERN`    | "useDebounce hook works well for search inputs"     |
+
+## Architecture
+
+```
+src/
+├── server/          # MCP handler (12+ layer brain pipeline) + dashboard
+├── memory/          # 25+ cognitive modules (decay, MMR, embedding cache, soul, diary, etc.)
+├── scanners/        # Project scanner, code verifier, export map, architecture graph
+├── db/              # SQLite storage, event log
+├── security/        # Rate limiter, encryption
+├── hooks/           # Git capture
+├── config/          # Configuration
+└── cli/             # Setup wizard
+```
+
+## Pricing & Features
+
+Cortex is open core. The basic version is free forever. To unlock deep cognitive features, upgrade to PRO.
+
+| Feature                             | FREE (npm install) | PRO ($9/mo) |
+| ----------------------------------- | :----------------: | :---------: |
+| **Memory Capacity**                 |    ∞ Unlimited     | ∞ Unlimited |
+| **Brain Layers**                    |     12+ (Full)     | 12+ (Full)  |
+| **All 16 Tools**                    |        Yes         |     Yes     |
+| **Auto-Learn**                      |        Yes         |     Yes     |
+| **Export Map (Anti-Hallucination)** |        Yes         |     Yes     |
+| **Architecture Graph**              |        Yes         |     Yes     |
+| **Git Memory**                      |        Yes         |     Yes     |
+| **Confidence Decay**                |        Yes         |     Yes     |
+| **Contradiction Detection**         |        Yes         |     Yes     |
+| **Priority Support**                |         —          |     Yes     |
+
+> **Launch Edition**: All features are currently free. Get started now and lock in lifetime access.
+
+### Activate PRO
+
+1. Get a license key from your [Cortex AI Dashboard](https://cortex-ai-iota.vercel.app/dashboard)
+2. Set it in your environment:
+
+    ```bash
+    # Option A: Environment variable
+    export CORTEX_LICENSE_KEY=CORTEX-XXXX-XXXX-XXXX-XXXX
+
+    # Option B: License file
+    echo CORTEX-XXXX-XXXX-XXXX-XXXX > ~/.cortex/license
+    ```
+
+3. Restart your IDE / MCP server.
+
+## Architecture
+
+```mermaid
+graph TB
+    AI["AI Client (Cursor, Claude, etc.)"]
+    MCP["MCP Server (stdio)"]
+    ML["Memory Layer"]
+    DB["SQLite Database"]
+    SEC["Security Layer"]
+    API["License API"]
+
+    AI -->|"JSON-RPC via stdio"| MCP
+    MCP --> ML
+    ML --> DB
+    MCP --> SEC
+    SEC -->|"verify license"| API
+
+    subgraph "Memory Layer"
+        ML --> EMB["Embedding Manager"]
+        ML --> AL["Auto-Learner"]
+        ML --> QG["Quality Gates"]
+        ML --> TD["Temporal Decay"]
+    end
+
+    subgraph "Retrieval"
+        ML --> HR["Hybrid Retriever"]
+        HR --> VS["Vector Search"]
+        HR --> FTS["Full-Text Search"]
+        HR --> RR["Recency Ranker"]
+    end
+```
+
+## FAQ / Troubleshooting
+
+<details>
+<summary><strong>Cortex doesn't start or my AI client can't connect</strong></summary>
+
+1. Make sure Node.js >=18 is installed: `node --version`
+2. Try running manually: `npx cortex-mcp` — check stderr for errors
+3. Check if another Cortex instance is running on the same workspace
+4. Delete the cache and restart: `rm -rf .ai/brain-data`
+ </details>
+
+<details>
+<summary><strong>Memories aren't being recalled</strong></summary>
+
+1. Confirm your AI client's system prompt includes the Cortex rules (run `cortex-setup` to install them)
+2. Check the dashboard at `http://localhost:3456` to see stored memories
+3. Verify memories exist: the AI should call `force_recall` at conversation start
+ </details>
+
+<details>
+<summary><strong>"better-sqlite3" build errors on install</strong></summary>
+
+`better-sqlite3` requires a C++ compiler:
+
+- **Windows**: Install [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
+- **macOS**: Run `xcode-select --install`
+- **Linux**: Run `sudo apt-get install build-essential python3`
+    </details>
+
+<details>
+<summary><strong>License key not working</strong></summary>
+
+1. Verify the key format: `CORTEX-XXXX-XXXX-XXXX-XXXX`
+2. Check your internet connection (license is verified online on first use)
+3. Clear the cache: `rm ~/.cortex/license-cache.json`
+4. Try setting it via environment variable: `export CORTEX_LICENSE_KEY=CORTEX-...`
+ </details>
+
+<details>
+<summary><strong>Dashboard not loading</strong></summary>
+
+1. Default port is 3456. Check if something else is using it: `lsof -i :3456`
+2. Set a custom port: `export CORTEX_PORT=4000`
+3. The dashboard URL is shown in your AI client's stderr on startup
+ </details>
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding conventions, and the PR process.
+
+## License
+
+MIT