Claude Cortex 🧠

Brain-like memory system for Claude Code - Solves the context compaction and memory persistence problems.

The Problem

Claude Code has fundamental limitations:

1. Context Window Exhaustion - Long sessions hit token limits
2. Compaction Loss - When context is summarized, important details are lost
3. No Persistence - Knowledge doesn't survive across sessions

The Solution

Claude Cortex works like a human brain:

• Short-term memory - Session-level, high detail, decays fast
• Long-term memory - Cross-session, consolidated, persists
• Episodic memory - Specific events and successful patterns
• Salience detection - Automatically identifies what's worth remembering
• Temporal decay - Memories fade but can be reinforced through access
• Consolidation - Like sleep, moves worthy memories to long-term storage

Quick Start

1. Install

Option A: Install via npm (Recommended)

npm install -g claude-cortex

Option B: Use with npx (no install)

Configure directly in .mcp.json (see step 2).

Option C: From source

git clone https://github.com/mkdelta221/claude-cortex.git
cd claude-cortex
npm install
npm run build

2. Configure Claude Code

Option A: Project-scoped (recommended for testing)

Create .mcp.json in your project directory:

{
  "mcpServers": {
    "memory": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "claude-cortex"]
    }
  }
}

Option B: Global (all projects)

Create ~/.claude/.mcp.json with the same content.

After adding the config, restart Claude Code and approve the MCP server when prompted.

3. Configure PreCompact Hook (Recommended)

Add to ~/.claude/settings.json for automatic memory extraction before compaction:

{
  "hooks": {
    "PreCompact": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "npx -y claude-cortex-hook pre-compact"
          }
        ]
      }
    ]
  }
}

This ensures important context is auto-saved before any compaction event.

4. Enable Proactive Memory (Recommended)

npx claude-cortex setup

This adds instructions to ~/.claude/CLAUDE.md so Claude proactively uses memory tools in all projects. Safe to run multiple times (idempotent).

5. Use It

The memory system integrates seamlessly with Claude Code. Here are the key tools:

Remember Something

Claude, remember that we're using PostgreSQL for the database.

Recall Information

Claude, what do you know about our database setup?

Get Context (Key for Compaction!)

Claude, get the context for this project.

Tools

| Tool | Description | |------|-------------| | remember | Store a memory with auto-categorization and salience detection | | recall | Search and retrieve memories (semantic search, filters) | | forget | Delete memories (single or bulk, with safety confirmations) | | get_context | THE KEY TOOL - Get relevant context, especially after compaction | | start_session | Start a session, get project context | | end_session | End session, trigger consolidation | | consolidate | Run memory consolidation manually | | memory_stats | View memory statistics | | export_memories | Export as JSON for backup | | import_memories | Import from JSON |

Resources

The server also exposes MCP resources:

| Resource | Description | |----------|-------------| | memory://context | Current memory context summary | | memory://important | High-priority memories | | memory://recent | Recently accessed memories |

How It Works

Salience Detection

Not everything is worth remembering. The system scores information on:

| Factor | Weight | Example | |--------|--------|---------| | Explicit request | 1.0 | "Remember this" | | Architecture decision | 0.9 | "We're using microservices" | | Error resolution | 0.8 | "Fixed by updating X" | | Code pattern | 0.7 | "Use this approach for auth" | | User preference | 0.7 | "Always use strict mode" | | Code references | 0.5 | Mentions specific files/functions | | Emotional markers | 0.5 | "Important", "critical" |

Temporal Decay

Like human memory:

score = base_salience × (0.995 ^ hours_since_access)

• Decay: Memories fade over time
• Reinforcement: Each access boosts score by 1.2×
• Consolidation: Frequently accessed short-term → long-term

Memory Types

| Type | Decay Rate | Use Case | |------|------------|----------| | Short-term | Fast (hourly) | Current session, debugging | | Long-term | Slow (daily) | Architecture, patterns | | Episodic | Medium | Specific events, learnings |

Solving the Compaction Problem

When Claude Code compacts context:

1. Before compaction - The PreCompact hook automatically extracts important content
2. After compaction - Use get_context to restore what's relevant

Automatic Memory Extraction (PreCompact Hook)

The system includes a hook that runs before every context compaction:

🧠 AUTO-MEMORY: 3 important items were automatically saved before compaction.
After compaction, use 'get_context' to retrieve your memories.

What gets auto-extracted:

• Decisions: "decided to...", "going with...", "chose..."
• Error fixes: "fixed by...", "the solution was...", "root cause..."
• Learnings: "learned that...", "discovered...", "turns out..."
• Architecture: "the architecture uses...", "design pattern..."
• Preferences: "always...", "never...", "prefer to..."
• Important notes: "important:", "remember:", "key point..."

Auto-extracted memories are:

• Tagged with auto-extracted for easy filtering
• Scored using salience detection (only high-scoring items saved)
• Limited to 5 per compaction to avoid noise

Example Workflow

# Session starts
Claude: Let me get the project context.
[Calls get_context tool]
> Found: PostgreSQL database, React frontend, auth uses JWT...

# Work happens, context grows...

# Compaction occurs, context is lost!

# You notice Claude forgot something:
You: Claude, what database are we using?
Claude: Let me check my memory.
[Calls recall tool with query "database"]
> Found: "Using PostgreSQL for the database" (architecture, 95% salience)

Configuration

Database Location

Default: ~/.claude-cortex/memories.db (with fallback to legacy ~/.claude-memory/ for existing users)

Custom location:

node dist/index.js --db /path/to/custom.db

Or in Claude config:

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/path/to/dist/index.js", "--db", "/path/to/custom.db"]
    }
  }
}

Tuning Parameters

In src/memory/types.ts:

export const DEFAULT_CONFIG = {
  decayRate: 0.995,              // Per-hour decay factor
  reinforcementFactor: 1.2,      // Access boost
  salienceThreshold: 0.3,        // Min score to keep
  consolidationThreshold: 0.6,   // Min for STM→LTM
  maxShortTermMemories: 100,
  maxLongTermMemories: 1000,
  autoConsolidateHours: 4,
};

Development

# Install dependencies
npm install

# Development mode (with tsx)
npm run dev

# Build
npm run build

# Watch mode
npm run watch

Dashboard (Optional)

The dashboard provides a 3D brain visualization of your memories with real-time updates.

Auto-Start on Login (Recommended)

npx claude-cortex setup              # Configure Claude for proactive memory use
npx claude-cortex service install    # Enable auto-start
npx claude-cortex service uninstall  # Remove auto-start
npx claude-cortex service status     # Check status

Works on macOS (launchd), Linux (systemd), and Windows (Startup folder). The dashboard and API server will start automatically on login.

Manual Start

# Terminal 1: Start API server
npm run dev:api

# Terminal 2: Start dashboard
cd dashboard && npm run dev

• Dashboard: http://localhost:3030
• API Server: http://localhost:3001

Features

• 3D Brain Visualization - Memories displayed as nodes in a neural network
• Search - Full-text search with autocomplete suggestions
• Filters - Filter by memory type (STM/LTM/Episodic) and category
• Statistics - System health, memory counts, category distribution
• Controls - Pause/resume memory creation, trigger consolidation
• Version Management - Check for updates, update, and restart server

Memory Visualization Colors

| Color | Category | |-------|----------| | Blue | Architecture | | Purple | Pattern | | Green | Preference | | Red | Error | | Yellow | Learning | | Cyan | Context |

How This Differs from Other Solutions

| Feature | Claude Cortex | Other MCP Memory Tools | |---------|---------------|------------------------| | Salience detection | ✅ Auto-detects importance | ❌ Manual only | | Temporal decay | ✅ Memories fade naturally | ❌ Static storage | | Consolidation | ✅ STM → LTM promotion | ❌ Flat storage | | Context injection | ✅ get_context tool | ❌ Manual recall | | Semantic search | ✅ FTS5 full-text | Varies | | Episodic memory | ✅ Event/pattern storage | ❌ Usually missing |

Support

If you find this project useful, consider supporting its development:

License

MIT