neo-cortex-mcp — Persistent Memory for AI Agents

The Problem

Claude Code is brilliant, but amnesiac

"We already discussed this three sessions ago..."

Every session starts from zero. You re-explain your architecture, your decisions, your preferences — over and over. Context windows compress. Conversations end. Knowledge disappears.

neo-cortex gives your AI agent a real memory — semantic search across hundreds of past conversations, automatic knowledge extraction, and intelligent consolidation.

$ claude # Without neo-cortex: > What's our auth architecture? I don't have context about your project. Could you describe it? # With neo-cortex: > What's our auth architecture? Based on session 12: JWT with PostgreSQL, decided 2 weeks ago. Reason: needed stateless auth for the microservices...

Features

Built for real-world AI development

Battle-tested across 50+ sessions and 900+ memories.

🔍

Dual Retrieval

Vector similarity + full-text search fused with Reciprocal Rank Fusion. Never miss relevant context.

📈

Energy Model

Memories gain energy when recalled, decay when forgotten. Ebbinghaus curve with execution-day tracking.

🧬

Deduplication

SimHash (64-bit, Hamming ≤ 3) prevents storing the same fact twice, even across sessions.

🌐

3D Concept Graph

NetworkX knowledge graph with spreading activation. Interactive 3D visualization in the web dashboard.

🤖

Meta-Reflection

The agent reflects on its own work patterns. Mature insights can graduate to identity amendments.

💥

Noise Filtering

7-category filter prevents junk — test output, file listings, micro-fixes never pollute your memory.

MCP Tools

11 tools, zero configuration

All tools appear automatically in Claude Code after installation.

Tool	Description
`memory_query`	Semantic search — "what did we decide about auth?"
`memory_search`	Filter by project, activity type, or text
`memory_timeline`	Recent memories in chronological order
`memory_stats`	Total memories, sessions, energy levels, version
`memory_get`	Full details of specific memories by ID
`memory_ingest`	Manually store a conversation turn
`memory_dream`	Consolidation — boost strong, decay noise
`memory_spontaneous`	Rediscover forgotten high-energy memories (7+ days stale)
`memory_rebuild`	Wipe and rebuild from conversation log
`memory_identity_review`	Self-reflection — propose identity insights with evidence
`memory_dashboard`	Web UI — browse memories + 3D concept graph

Get Started

Up and running in 3 minutes

Two free API keys. One JSON file. That's it.

1 Get free API keys

Both services offer generous free tiers for development.

# Embeddings (vector search) https://jina.ai/ # Knowledge distillation https://ai.google.dev/

2 Create .mcp.json

Add this file to your project root:

{ "mcpServers": { "neo-cortex": { "command": "uvx", "args": [ "--from", "neo-cortex-mcp@latest", "neo-cortex-mcp" ], "env": { "JINA_API_KEY": "your-key", "GEMINI_API_KEY": "your-key" } } } }

3 Start Claude Code

Auto-bootstraps on first launch. Restart once to activate hooks.

# First launch $ claude ✓ Session hooks installed ✓ cortex_db/ created Restart to activate. # After restart $ claude ✓ Loaded 0 memories (first session) ✓ 11 MCP tools available ✓ Memory is active

4 Add to CLAUDE.md (recommended)

Teach Claude when to use its memory:

# Memory This project uses neo-cortex for persistent memory across sessions. ## Rules - ALWAYS use `memory_query` before saying "I don't know" about past work - Cortex is the primary source of truth for project history - Conversations are captured automatically via hooks

One-Click Install

Let Claude Code do it for you

Copy this prompt and paste it into your Claude Code session. It will check everything, install what's missing, and configure neo-cortex automatically.

# Install neo-cortex-mcp — Persistent Memory for Claude Code
# This installation requires 3 steps with 2 restarts.
# After each step, tell the user what you did and ask them to restart.

## STEP 1 — Check prerequisites and create config files

1a. Check Python >= 3.12
   Run: python3 --version
   If missing or < 3.12: install via system package manager
   (apt: sudo apt install python3.12, brew: brew install python@3.12)

1b. Check uv (Python package manager)
   Run: uv --version
   If missing: curl -LsSf https://astral.sh/uv/install.sh | sh
   Verify uvx command works after install.

1c. Get API keys
   Ask the user for two API keys:
   - JINA_API_KEY — from https://jina.ai/ (free tier, for embeddings)
   - GEMINI_API_KEY — from https://ai.google.dev/ (free tier, for distillation)
   Show the URLs and ask the user to provide the keys.

1d. Create .mcp.json
   Create .mcp.json in the project root with:
   {
     "mcpServers": {
       "neo-cortex": {
         "command": "uvx",
         "args": ["--from", "neo-cortex-mcp@latest", "neo-cortex-mcp"],
         "env": {
           "JINA_API_KEY": "<key-from-1c>",
           "GEMINI_API_KEY": "<key-from-1c>"
         }
       }
     }
   }
   If .mcp.json already exists, merge the neo-cortex entry into it.

1e. Add to CLAUDE.md
   Add this block to the project's CLAUDE.md (create if missing):

   # Memory
   This project uses neo-cortex for persistent memory.
   ## Rules
   - ALWAYS use `memory_query` before saying "I don't know"
   - Use `memory_search` to filter by project or activity
   - Use `memory_timeline` at session start for recent context
   - Cortex is the primary source of truth for project history
   - Conversations are captured automatically via hooks

1f. Tell the user:
   "Done! I created .mcp.json and CLAUDE.md.
   Now please RESTART Claude Code so the MCP server can start.
   After restart, type: Check neo-cortex installation"

## STEP 2 — After first restart: verify MCP and hooks
(The user will restart and type "Check neo-cortex installation")

2a. Test MCP connection
   Run: memory_stats
   If it works: the MCP server is running.
   If it fails: check .mcp.json syntax and API keys.

2b. Check hooks were auto-installed
   Read .claude/settings.json — it should now contain
   SessionStart and Stop hooks (auto-installed by neo-cortex).
   If the hooks are there, tell the user:
   "MCP server is working! Hooks were auto-installed.
   Please RESTART Claude Code one more time to activate the hooks.
   After restart, type: Verify neo-cortex memory"

   If hooks are NOT there, something went wrong with bootstrap.
   Check that .mcp.json has the correct neo-cortex entry.

## STEP 3 — After second restart: everything is active
(The user will restart and type "Verify neo-cortex memory")

3a. Confirm hooks fired
   You should see cortex timeline output at startup (session context).
   Run memory_stats to confirm connection.

3b. Tell the user:
   "All set! neo-cortex memory is fully active.
   - Sessions are captured automatically when you exit
   - Knowledge is distilled in the background
   - Use memory_query to search past conversations
   - 11 MCP tools are available
   Your AI now remembers everything."

This prompt works with Claude Code (Anthropic CLI). Paste it at the start of a new session.

You build.
It remembers.

Capture

Distill

Embed

Store

Dream

Dual Retrieval

Energy Model

Deduplication

3D Concept Graph

Meta-Reflection

Noise Filtering

1 Get free API keys

2 Create .mcp.json

3 Start Claude Code

4 Add to CLAUDE.md (recommended)

Python ≥ 3.12

uv (astral.sh)

Claude Code

Free API keys

You build.It remembers.

Capture

Distill

Embed

Store

Dream

Dual Retrieval

Energy Model

Deduplication

3D Concept Graph

Meta-Reflection

Noise Filtering

1 Get free API keys

2 Create .mcp.json

3 Start Claude Code

4 Add to CLAUDE.md (recommended)

Python ≥ 3.12

uv (astral.sh)

Claude Code

Free API keys

You build.
It remembers.