neural-memory

NeuralMemory

Reflex-based memory system for AI agents — retrieval through activation, not search.

NeuralMemory stores experiences as interconnected neurons and recalls them through spreading activation, mimicking how the human brain works. Instead of searching a database, memories surface through associative recall — activating related concepts until the relevant memory emerges.

28 MCP tools · 11 memory types · 24 synapse types · Schema v20 · 2860+ tests

Why Not RAG / Vector Search?

Aspect	RAG / Vector Search	NeuralMemory
Model	Search engine	Human brain
LLM/Embedding	Required (embedding API calls)	None — pure algorithmic graph traversal
Query	"Find similar text"	"Recall through association"
Structure	Flat chunks + embeddings	Neural graph + synapses
Relationships	None (just similarity)	Explicit: CAUSED_BY, LEADS_TO, RESOLVED_BY, etc.
Temporal	Timestamp filter	Time as first-class neurons
Multi-hop	Multiple queries needed	Natural graph traversal
Lifecycle	Static	Decay, reinforcement, consolidation
API Cost	~$0.02/1K queries	$0.00 — fully offline

Example: "Why did Tuesday's outage happen?"

• RAG: Returns "JWT caused outage" (missing why we used JWT)
• NeuralMemory: Traces outage ← CAUSED_BY ← JWT ← SUGGESTED_BY ← Alice → full causal chain

---

Installation

pip install neural-memory

With optional features:

pip install neural-memory[server]   # FastAPI server + dashboard
pip install neural-memory[extract]  # PDF/DOCX/PPTX/HTML/XLSX extraction
pip install neural-memory[nlp-vi]   # Vietnamese NLP
pip install neural-memory[all]      # All features

Quick Setup

Claude Code (Plugin — Recommended)

/plugin marketplace add nhadaututtheky/neural-memory
/plugin install neural-memory@neural-memory-marketplace

That's it. MCP server, skills, commands, and agent are all configured automatically via uvx.

OpenClaw (Plugin)

pip install neural-memory
npm install -g @neuralmemory/openclaw-plugin

Then set the memory slot in ~/.openclaw/openclaw.json:

{ "plugins": { "slots": { "memory": "neuralmemory" } } }

Restart the gateway. See the full setup guide.

Cursor / Windsurf / Other MCP Clients

pip install neural-memory

Then add to your editor's MCP config (Cursor: .cursor/mcp.json, Windsurf: ~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "neural-memory": {
      "command": "nmem-mcp"
    }
  }
}

The editor spawns nmem-mcp automatically via stdio — no manual server start needed. No nmem init needed — auto-initializes on first use.

Usage

CLI

# Store memories (type auto-detected)
nmem remember "Fixed auth bug with null check in login.py:42"
nmem remember "We decided to use PostgreSQL" --type decision
nmem todo "Review PR #123" --priority 7

# Recall memories
nmem recall "auth bug"
nmem recall "database decision" --depth 2

# Shortcuts
nmem a "quick note"           # Short for remember
nmem q "auth"                 # Short for recall
nmem last 5                   # Last 5 memories
nmem today                    # Today's memories

# Get context for AI injection
nmem context --limit 10 --json

# Brain management
nmem brain list
nmem brain create work
nmem brain use work
nmem brain health
nmem brain export -o backup.json
nmem brain import backup.json

# Codebase indexing
nmem index src/               # Index code into neural memory

# Memory lifecycle
nmem decay                    # Apply forgetting curve
nmem consolidate              # Prune, merge, summarize
nmem cleanup                  # Remove expired memories

# Visual tools
nmem serve                    # Start FastAPI server
# Then open http://localhost:8000/ui for React dashboard