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.

38 MCP tools · 11 memory types · 24 synapse types · Schema v21 · 3200+ tests · Cognitive reasoning layer

Why Not RAG / Vector Search?

Aspect	RAG / Vector Search	NeuralMemory
Model	Search engine	Human brain
LLM/Embedding	Required (embedding API calls)	Optional — core recall is 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 (optional embeddings available)

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[embeddings]   # Local embedding (cross-language recall)
pip install neural-memory[all]          # All features

Optional: Embedding for Cross-Language Recall

Core recall works without embeddings. Enable embeddings to recall memories across languages (e.g., search in Vietnamese, find English memories):

# ~/.neuralmemory/config.toml
[embedding]
enabled = true
provider = "auto"    # Auto-detects: Ollama → sentence-transformers → Gemini → OpenAI

Or pick a specific provider: sentence_transformer (free/local), ollama (local via Ollama API), gemini (Google free tier), openai (paid). See the Embedding Setup Guide for details.

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

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