Package Exports

@londer/cortex
@londer/cortex/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@londer/cortex) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Cortex

A high-performance, locally-hosted AI memory system that stores, indexes, and retrieves contextual knowledge via MCP (Model Context Protocol). Designed for Claude Code, but works with any MCP client.

Installation

npm install -g @londer/cortex

Or from source:

git clone https://github.com/londer/cortex.git
cd cortex
npm install
npm run build

Quick Start

# 1. Set up storage backends (Qdrant + Neo4j via Docker)
cortex setup

# 2. Start the MCP server
cortex serve

Claude Code Integration

# Add Cortex to Claude Code
claude mcp add cortex -- cortex serve

# Generate Claude Code instructions for your project
cortex init

# Or set up global instructions (applies to all projects)
cortex init --global

Or manually add to your MCP config:

{
  "servers": {
    "cortex": {
      "command": "cortex",
      "args": ["serve"]
    }
  }
}

LLM Setup (Optional)

Cortex works fully without an API key. Adding one unlocks higher-quality extraction and smart consolidation.

# Via CLI
cortex config set anthropic_api_key sk-ant-your-key-here

# Or via environment variable
export ANTHROPIC_API_KEY=sk-ant-your-key-here

Ollama (Local LLM)

For privacy-first LLM extraction without an API key, install Ollama:

# Check Ollama status
cortex ollama status

# Pull the default model
cortex ollama pull

# Or configure a different model
cortex config set ollama_model mistral

Extraction Tiers

Cortex uses a tiered entity extraction system:

Tier	Method	Quality	Latency	Cost	Requirements
1	Regex + Heuristics	Basic	< 1ms	Free	Always available
2	NLP (compromise.js)	Good	< 50ms	Free	Always available
2.5	Ollama (local LLM)	Good+	1-5s	Free	Ollama running locally
3	LLM (Claude API)	Best	500ms-2s	~$0.002/call	API key required

The system automatically selects the best available tier (3 → 2.5 → 2 → 1) and falls back gracefully.

Capability Matrix

Feature	No API Key	With Ollama	With API Key
Entity extraction	Tier 1-2 (regex + NLP)	Tier 2.5 (local LLM)	Tier 3 (Claude)
Relationship detection	Basic verb patterns	LLM-powered	Full semantic understanding
Auto-extraction	Local heuristics	Ollama-powered	LLM-powered analysis
Consolidation: near-identical dedup	Yes (> 0.95 similarity)	Yes	Yes
Consolidation: smart merge	Flagged for review	Yes	Yes
Consolidation: contradiction resolution	No	Yes	Yes
memory_ingest	Tier 1-2 extraction	Tier 2.5 extraction	Tier 3 extraction
Cross-project sharing	Full access	Full access	Full access
Access tracking & stats	Full access	Full access	Full access

Available Tools

Tool	Description
`memory_store`	Store a memory. Auto-embeds content, stores metadata, links entities.
`memory_search`	Semantic search with scope boosting.
`memory_relate`	Create entity relationships in the knowledge graph.
`memory_graph_query`	Traverse the knowledge graph from an entity.
`memory_context`	Smart context retrieval combining semantic + graph + recency.
`memory_forget`	Delete a memory from all stores (requires confirmation).
`memory_ingest`	Ingest raw text and extract memories/entities/relationships.
`memory_consolidate`	Merge redundant memories. Supports dry_run preview.
`memory_config`	View/modify runtime configuration (including API key).
`memory_stats`	Aggregate statistics: totals, breakdowns, access patterns, staleness.
`memory_share`	Cross-project sharing: promote visibility, link/unlink projects.

CLI Reference

cortex serve                      Start the MCP server (stdio transport)
cortex setup                      Start production Qdrant + Neo4j (ports 16333/17687)
cortex setup --dev                Start dev Qdrant + Neo4j (ports 26333/27687)
cortex setup --stop               Stop containers
cortex init                       Generate Cortex instructions for project CLAUDE.md
cortex init --global              Generate global instructions (~/.claude/CLAUDE.md)
cortex config get                 Show current configuration
cortex config set <key> <value>   Set a runtime config value
cortex consolidate                Run manual consolidation
cortex stats                      Show memory statistics and staleness info
cortex ollama status              Check Ollama availability and installed models
cortex ollama pull [model]        Pull an Ollama model
cortex version                    Show version
cortex help                       Show help

Configuration

Configuration is loaded from environment variables with sensible defaults. See .env.example for all options.

Key settings:

Variable	Default	Description
`QDRANT_URL`	`http://localhost:16333`	Qdrant server URL
`NEO4J_URI`	`bolt://localhost:17687`	Neo4j bolt URI
`SQLITE_PATH`	`~/.cortex/cortex.db`	SQLite database path
`ANTHROPIC_API_KEY`	(empty)	Anthropic API key (optional)
`CORTEX_EXTRACTION_TIER`	`auto`	`auto`, `local-only`, or `llm-preferred`
`CORTEX_AUTO_EXTRACT`	`true`	Enable auto-extraction from conversations
`CORTEX_CONSOLIDATION_ENABLED`	`true`	Enable periodic memory consolidation
`CORTEX_STALENESS_THRESHOLD_DAYS`	`90`	Days before a memory is considered stale
`CORTEX_OLLAMA_ENABLED`	`true`	Enable Ollama local LLM
`CORTEX_OLLAMA_URL`	`http://localhost:11434`	Ollama server URL
`CORTEX_OLLAMA_MODEL`	`llama3.2`	Ollama model name

Runtime overrides persist to ~/.cortex/runtime-config.json.

Development

# Run with hot reload
npm run dev

# Run tests (requires Docker backends running)
npm test

# Build
npm run build

# Release (bump version, update changelog, create tag)
npm run release

Architecture

Claude Code
    │ MCP (stdio)
    ▼
┌──────────────────────────────────────┐
│          Cortex MCP Server           │
│            (TypeScript)              │
├──────────────────────────────────────┤
│  Extraction    │ Consolidation       │
│  Tier 1-3+     │ LLM / Ollama / Local│
│  Auto-extract  │ Cluster + Merge     │
├──────────────────────────────────────┤
│         Orchestration Layer          │
│  Scope inference, ranking, dedup     │
├─────────┬──────────┬─────────────────┤
│ Qdrant  │  Neo4j   │     SQLite      │
│ vectors │  graph   │    metadata     │
└─────────┴──────────┴─────────────────┘
         ▲                    ▲
  HuggingFace            Anthropic API
  Transformers.js         (optional)
                          Ollama
                          (optional)

License

MIT - Arthur Lonfils / Londer