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.

Why Not RAG / Vector Search?

Aspect	RAG / Vector Search	NeuralMemory
Model	Search engine	Human brain
Query	"Find similar text"	"Recall through association"
Structure	Flat chunks + embeddings	Neural graph + synapses
Relationships	None (just similarity)	Explicit: CAUSED_BY, LEADS_TO, DISCUSSED
Temporal	Timestamp filter	Time as first-class neurons
Multi-hop	Multiple queries needed	Natural graph traversal
Lifecycle	Static	Decay, reinforcement, consolidation

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[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.

Cursor / Windsurf / Other MCP Clients

pip install neural-memory

Then add to your editor's MCP config:

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

No nmem init needed — the MCP server 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 dashboard                # Rich terminal dashboard
nmem ui                       # Interactive memory browser
nmem graph "auth"             # Visualize neural connections

Python API

import asyncio
from neural_memory import Brain
from neural_memory.storage import InMemoryStorage
from neural_memory.engine.encoder import MemoryEncoder
from neural_memory.engine.retrieval import ReflexPipeline

async def main():
    storage = InMemoryStorage()
    brain = Brain.create("my_brain")
    await storage.save_brain(brain)
    storage.set_brain(brain.id)

    # Encode memories
    encoder = MemoryEncoder(storage, brain.config)
    await encoder.encode("Met Alice to discuss API design")
    await encoder.encode("Decided to use FastAPI for backend")

    # Query through activation
    pipeline = ReflexPipeline(storage, brain.config)
    result = await pipeline.query("What did we decide about backend?")
    print(result.context)  # "Decided to use FastAPI for backend"

asyncio.run(main())

MCP Tools (Claude Code / Cursor)

Once configured, these tools are available to your AI assistant: