Cortex is a local, privacy-first "Long Term Memory" system for AI agents. It intelligently stores and retrieves information from your workflow (IDEs, terminals, chat) using a Hybrid GraphRAG architecture that combines semantic search with graph-based reasoning.

It operates as a Model Context Protocol (MCP) server, making it instantly compatible with Claude Desktop, Cursor, VSCode (GitHub Copilot), and other AI clients.

You can run Cortex via Docker or Python (Recommended) directly.

No Python setup required. Runs the MCP server on port 8000.

# 1. Clone and start
git clone https://github.com/yourusername/cortex.git
cd Cortex
docker compose up -d

# 2. Verify it's running
curl http://localhost:8000/health
# Output: {"status": "healthy", "server": "Cortex MCP"}

Prerequisites: Python 3.11+

1. Setup Environment

   python -m venv venv
   # Windows: venv\Scripts\activate
   # Mac/Linux: source venv/bin/activate
   pip install -r requirements.txt

2. Download Models

   python -m spacy download en_core_web_sm

3. Run Server

   # Starts HTTP server on port 8000
   python src/cortex/main.py --host 0.0.0.0 --port 8000

Cortex uses the Model Context Protocol. Once the server is running (usually at http://localhost:8000/mcp), connect your favorite AI editor.

Add this to your config file:

• Win: %APPDATA%\Claude\claude_desktop_config.json
• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "cortex": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Add to .vscode/mcp.json or the extension settings:

{
  "mcpServers": {
    "cortex": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Cortex generates a beautiful 3D/2D interactive dashboard to explore your knowledge graph. See how memories, topics, and projects interconnect in real-time.

3D Neural Network View

Explore your knowledge graph in immersive 3D space with animated data flows

2D Strategic Overview

Switch to 2D mode for precise navigation and analysis

Features:

• 🔄 Toggle 3D/2D views with a single click
• 🎯 Click nodes to see detailed information (source, timestamp, category, connections)
• ✨ Animated particle flows showing data relationships
• 🌌 Starfield background for cinematic experience (3D mode)
• 📊 Live statistics showing node and link counts
• 🎨 Color-coded nodes: Memory (red), Topics (green), Projects (blue)

Generate your own dashboard with the visualize_brain tool or run the demo:

python demo_scenario.py
# Open demo_dashboard.html manually

Cortex implements a Hybrid GraphRAG approach. It doesn't just match text; it understands relationships.

graph TD
    Client[AI Agent / Client] <-->|MCP Protocol| API[Cortex Server]
    
    subgraph "Cortex Core"
        API --> NLP["Intelligence Layer<br/>(spaCy + PII Filter)"]
        
        NLP -->|Entities| Graph["Associative Store<br/>(Kùzu Graph DB)"]
        NLP -->|Embeddings| Vector["Semantic Store<br/>(LanceDB)"]
        
        Graph <-->|Relations| Vector
    end
    
    subgraph "Performance"
        Cache["L1 Cache<br/>Embeddings + Queries"] -.-> API
        Monitor["Metrics & Stats"] -.-> API
    end

1. 🔍 Semantic Store (Hippocampus): LanceDB + FastEmbed. Handles vector similarity search with an automatic L2 distance threshold (< 0.85).
2. 🕸️ Associative Store (Cortex): Kùzu Graph DB. Links memories to Topics, Projects, and Entities. Allows 2-hop neighbor traversal.
3. 🤖 Intelligence Layer: Spacy. Automatic extraction of PERSON, ORG, PRODUCT and PII Sanitization (redacting emails, keys, etc.).

Your AI agent will have access to these tools automatically:

Saves information with automatic entity extraction and privacy cleaning.

{"content": "We chose FastAPI because of its async performance", "category": "decision", "project": "Backend-v2"}

Retrieves relevant memories using hybrid ranking (Vector + Graph scores).

{"query": "Why did we choose FastAPI?", "limit": 5}

Generates an interactive D3.js dashboard of your knowledge graph. Returns a path to dashboard.html.

Returns real-time metrics (cache hit rates, operation times, memory usage).

Configure Cortex via environment variables (in .env or Docker Compose):

Cortex is designed for sensitive data.

• Local First: No data is sent to OpenAI/Anthropic clouds for storage.
• PII Redaction: 11 patterns are automatically stripped before storage:
  • email, phone, ip_address, credit_card
  • api_keys (sk-...), aws_keys, jwt_tokens
  • crypto_addresses, ssn, passwords

We maintain 100% test coverage.

# Run full suite
pytest tests/ -v

# Check coverage
pytest tests/ --cov=src/cortex

Project Structure:

Cortex/
├── src/cortex/
│   ├── intelligence/  # NLP & Privacy logic
│   ├── storage/       # LanceDB & Kùzu wrappers
│   └── server.py      # MCP Implementation
├── tests/             # 40/40 Passing Tests
└── docker-compose.yml

Contributions are welcome! Please follow the Singleton Pattern used in storage/manager.py to ensure thread safety.

1. Fork & Branch (feature/amazing-feature)
2. Test (pytest)
3. PR with description