npm install -g cortex-local

Local Memory for AI Assistants

cortex-local is a lightweight MCP server and CLI backed by SQLite. Zero setup — no Docker, no PostgreSQL, no API key. Install once and your AI tools remember everything.

View on npm GitHub →API Reference →

SQLite + FTS5

No server required

All data lives in ~/.cortex-local/memories.db. Works fully offline.

MCP native

Claude, Cursor & more

Exposes 6 tools via the Model Context Protocol. Auto-configures on install.

HTTP REST API

Works with Codex

Run cortex-local serve for a local REST endpoint any tool can hit.

MIT · Node 18+

Open source

Uses built-in node:sqlite on Node 22.5+. Zero extra deps for most users.

Install & Setup

The postinstall script automatically patches any existing Claude Desktop or Cursor config files. Nothing is created if the config file doesn't already exist — no surprises.

Installation

# Install globally — auto-configures Claude Desktop & Cursor
npm install -g cortex-local

# Or configure manually for a specific client
cortex-local setup claude       # Claude Desktop
cortex-local setup cursor       # Cursor
cortex-local setup claude-code  # Claude Code CLI
cortex-local setup codex        # Codex (shows HTTP instructions)

How It Works

Install once

npm install -g cortex-local patches your Claude Desktop and Cursor MCP configs automatically. No manual JSON editing.

AI tools use the MCP tools

Claude calls remember, recall, and list_memories during your conversations. Memories persist across sessions in a local SQLite file.

Every session picks up where you left off

Your projects, preferences, and decisions are recalled automatically. You never repeat yourself between sessions.

MCP Tools

Once connected, Claude (or any MCP client) can call these six tools automatically:

remember

Store a memory with optional tags and importance score (0–1).

recall

Full-text search across memories. Returns ranked results with scores.

forget

Delete a memory by ID.

list_memories

List recent memories with optional tag filters and limit.

update_memory

Update the content, tags, or importance of an existing memory.

memory_stats

Return total count, oldest, and newest memory timestamps.

Claude Code Setup

Claude Code uses its own config. Add cortex-local globally with one command, or per-project via .claude/settings.json.

Claude Code CLI

# One-time setup via Claude Code CLI
claude mcp add cortex-local cortex-local

# Or add per-project in .claude/settings.json
{
  "mcpServers": {
    "cortex-local": { "command": "cortex-local" }
  }
}

CLI Reference

Manage memories directly from the terminal — useful for scripting, backup automation, or quick lookups.

CLI commands

# Add a memory
cortex-local add "Prefer strict TypeScript and functional patterns" --tag coding

# Search memories
cortex-local search "TypeScript preferences" --limit 5

# List all memories
cortex-local list --limit 20 --tag coding

# Summary statistics
cortex-local stats

# Export / import
cortex-local export --out backup.json
cortex-local import backup.json

# Backup / restore the SQLite database
cortex-local backup --out ~/backups/
cortex-local restore ~/backups/memories-2026-05-09.db

# Start the HTTP REST API (for Codex or scripts)
cortex-local serve --port 3001 --key my-secret

HTTP REST API

Run cortex-local serve to start a local REST server — useful for Codex, scripts, or any tool without native MCP support. Optionally protect it with --key.

Method	Path	Description
GET	/memories	List memories (supports ?tag=&limit=)
POST	/memories	Add a memory { content, tags?, importance? }
GET	/memories/search	Full-text search (?q=&limit=&tag=)
DELETE	/memories/:id	Delete a memory by ID
GET	/export	Export all memories as JSON
POST	/import	Import memories from JSON
GET	/health	Health check

HTTP API examples

# Start the REST server
cortex-local serve --port 3001

# Add a memory
curl -X POST http://localhost:3001/memories \
  -H "Content-Type: application/json" \
  -d '{"content": "Prefer functional patterns", "tags": ["coding"]}'

# Search
curl "http://localhost:3001/memories/search?q=TypeScript&limit=5"

# Health check
curl http://localhost:3001/health

Configuration

Variable	Default	Description
KNOL_LOCAL_DB	~/.cortex-local/memories.db	Override the SQLite database path

Node 22.5+ uses the built-in node:sqlite — no extra dependencies. Older runtimes (Claude Desktop embeds Node 18) auto-install better-sqlite3 during postinstall.

cortex-local vs Cortex

	cortex-local	Cortex (full)
Setup	npm install -g	Docker / self-host / cloud
Storage	SQLite (local file)	PostgreSQL + pgvector
Retrieval	Full-text (FTS5)	Vector + BM25 + graph (hybrid)
Knowledge graph	—	✓
Multi-user	—	✓ (RLS isolation)
Memory decay	—	✓
HTTP REST API	✓ (local)	✓ (production-grade)
MCP tools	6 tools	6 tools + graph query
Conflict detection	—	✓
Best for	Personal use / local dev	Teams & production apps

Ready to give your AI persistent memory?

One command. Works immediately with Claude Desktop, Cursor, and Claude Code. Upgrade to the full Cortex stack when you need teams, graphs, or hybrid retrieval.

npm install -g cortex-local

View on npm Star on GitHub See Full Cortex Plans