cortex-mcp 2.6.0 → 2.7.1

package/README.md

@@ -1,393 +1,224 @@
-# 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.4
-
-- **🧠 Smart importance scoring** — Memories ranked by type (CORRECTION > INSIGHT) + content signals (file paths, error keywords boost importance)
-- **🏷️ Auto topic tags** — Memories auto-tagged with technologies, domains, and actions (`['typescript', 'auth', 'database']`)
-- **🏁 Task completion tracking** — Say "finished SEO work" and old SEO memories get demoted automatically
-- **🔍 Resolved memory filtering** — FTS search, ranker, and context builder all exclude completed work
-- **🛡️ Code block safety** — Auto-learn no longer extracts from code blocks (no `const foo = bar()` as memories)
-- **📊 Dashboard auto-refresh** — Updates every 30 seconds
-- **Free LLM integration** — Add `OPENROUTER_API_KEY` for 3x smarter memory extraction (zero cost!)
-- **40+ auto-learn patterns** — Captures decisions, corrections, conventions, bug fixes from AI responses
-- **Error fingerprints** — Auto-captures stack traces, TS errors, npm failures for instant fix recall
-- **Success tracking** — Detects "that worked!" and stores proven approaches
-- **Brain Health Score** — Gamified 0-100 score with grades (Newborn → Genius)
-- **Git-enhanced resume** — Shows recent commits + branch context when resuming work
-
-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                                                                |
-
-### 12+ Layer Brain Pipeline
-
-Every conversation starts with `force_recall`, which runs 12+ layers (layers 6-12 run **in parallel** for speed):
-
-| Layer | Feature                                                       | Parallel? |
-| :---: | ------------------------------------------------------------- | :-------: |
-|   0   | Session management — track what you're working on             |     —     |
-|   1   | Maintenance — decay, boost corrections, consolidate           |     —     |
-|   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           |    ✅     |
-|   8   | Workspace git — branch, recent commits, diffs                 |    ✅     |
-|  8.5  | Git memory — auto-capture commits + file changes              |    ✅     |
-|   9   | Topic search — FTS + decay + causal chain traversal           |    ✅     |
-|  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/          # 17 cognitive modules (decay, attention, anticipation, 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
+# 🧠 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 35 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 |
+
+---
+
+## 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.*