Cortex

Cortex — The Universal Hive Mind 🧠

Version: 1.0 (Production-Ready Hybrid Stack)

A privacy-first, local Long Term Memory system for AI agents with hybrid GraphRAG retrieval.

Features • Quick Start • Architecture • Usage & Tools

---

🎯 Overview

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.

✨ Key Features

Feature	Description
🔒 Privacy-First	All data stays local. Automatic PII detection & redaction (11 patterns).
🚀 High Performance	~800MB memory savings via singleton patterns + intelligent caching.
🧩 Hybrid Retrieval	Semantic search (LanceDB) + Graph reasoning (Kùzu) combined.
🤝 Multi-Agent	Safe concurrent access for multiple agents (Windows/Linux compatible).
📊 Monitoring	Real-time metrics, cache stats, and get_system_stats() tool.
🎨 Visualization	Auto-generated interactive HTML dashboard of your knowledge graph.

---

🚀 Quick Start

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

🐳 Option 1: Docker

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"}

🐍 Option 2: Python Manual Setup (Recommended)

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
   

---

🔌 Connecting MCP Clients

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

🤖 Claude Desktop

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"
    }
  }
}

💻 VSCode (GitHub Copilot / Cline)

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

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

[!TIP] Testing the connection: Ask your AI "What is your memory status?" or "Store this: I am working on Project X".

---

🎨 Interactive Visualization

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

---

🧠 Architecture

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

The Three Layers

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.).

---

🏃‍♂️ Usage & Tools

Your AI agent will have access to these tools automatically:

store_memory

Saves information with automatic entity extraction and privacy cleaning.

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

recall

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

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

visualize_brain

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

get_system_stats

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

---

⚙️ Configuration

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

Variable	Default	Description
CORTEX_STORAGE_DIR	.cortex_storage	Location of DB files
CORTEX_THRESHOLD	0.85	Similarity strictness (lower = stricter)
CORTEX_SEARCH_LIMIT	5	Max results returned by recall queries
CORTEX_ENABLE_CACHE	true	Enable in-memory caching
CORTEX_PII_DETECTION	true	Enable auto-redaction of secrets
CORTEX_LOG_LEVEL	INFO	Verbosity (DEBUG, INFO, ERROR)

---

🔒 Privacy & Security

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

[!WARNING] While Cortex sanitizes data, always ensure the storage directory (.cortex_storage) is secured with appropriate file system permissions.

---

🧪 Development & Testing

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

---

🤝 Contributing

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

---

⭐ Star this repo if Cortex helps your AI agents remember! ⭐

Built with ❤️ for the future of Agentic AI