DEV Community

Cover image for Neural Memory: How Spreading Activation Gives AI Agents a Real Memory System
Nam Nguyễn
Nam Nguyễn

Posted on

Neural Memory: How Spreading Activation Gives AI Agents a Real Memory System

#ai #claudecode #mcp

The Problem

Every AI coding session starts from zero. You explain your project architecture, your conventions, your past decisions — and the AI forgets all of it when the session ends.

Most solutions reach for RAG: embed text into vectors, search by similarity, return chunks. It works for document retrieval, but it's a poor model for memory. When you remember something, you don't search a database — you associate. One thought triggers another, which triggers another, until the relevant memory surfaces.

A Different Approach: Neural Graphs

Neural Memory stores memories as a graph of typed neurons connected by typed synapses:

outage ← CAUSED_BY ← JWT_decision ← SUGGESTED_BY ← Alice ← DECIDED_AT ← Tuesday_meeting
Enter fullscreen mode Exit fullscreen mode

When you ask "why did the outage happen?", it doesn't just find text containing "outage." It activates the outage neuron, and activation spreads through the graph following synapse weights. You get the full causal chain — not just the closest text match.

RAG vs Spreading Activation

Aspect RAG / Vector Search Neural Memory
Model Search engine Human brain
LLM/Embedding Required Optional — core recall is pure graph traversal
Query "Find similar text" "Recall through association"
Relationships None (just similarity) Explicit: CAUSED_BY, LEADS_TO, RESOLVED_BY
Multi-hop Multiple queries Natural graph traversal
API Cost ~$0.02/1K queries $0.00 — fully offline

How It Works

1. Encoding

When you tell the AI to remember something, Neural Memory:

  • Extracts entities, keywords, temporal markers
  • Creates typed neurons (ENTITY, CONCEPT, ACTION, TEMPORAL, etc.)
  • Creates typed synapses between them (24 relationship types)
  • Groups related neurons into a Fiber (episodic memory bundle)

2. Retrieval (Spreading Activation)

When you recall:

  1. Seed activation: neurons matching your query get initial activation
  2. Spreading: activation propagates through synapses, weighted by strength
  3. Decay: activation decreases with each hop (configurable)
  4. Threshold: only neurons above threshold are included in results
  5. Context assembly: top-activated neurons are assembled into a coherent response

This naturally handles multi-hop queries. "Who suggested the thing that caused the outage?" follows the chain without explicit graph queries.

3. Consolidation

Memories have a lifecycle:

  • Decay: unused synapses weaken over time
  • Reinforcement: recalled memories get stronger
  • Pruning: orphan neurons (no connections) get cleaned up
  • Merging: duplicate information gets consolidated

28 MCP Tools

Neural Memory exposes 28 tools via the Model Context Protocol:

Tool What it does
nmem_remember Store a memory with automatic extraction
nmem_recall Retrieve memories through spreading activation
nmem_context Load recent memories at session start
nmem_explain Show WHY two concepts are connected (BFS path)
nmem_habits Detect recurring patterns in your workflow
nmem_consolidate Run memory lifecycle (decay, prune, merge)
nmem_health Health diagnostics with actionable recommendations
nmem_session Save/restore session state

Plus 20 more for brain management, import/export, training, and diagnostics.

Quick Start 

pip install neural-memory
Enter fullscreen mode Exit fullscreen mode

Claude Code (Plugin) 

/plugin marketplace add nhadaututtheky/neural-memory
Enter fullscreen mode Exit fullscreen mode

Manual MCP Config 

{
  "mcpServers": {
    "neural-memory": {
      "command": "uvx",
      "args": ["neural-memory"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Optional: Cross-Language Embeddings

Core recall works without embeddings. Enable for cross-language search:

# ~/.neuralmemory/config.toml
[embedding]
enabled = true
provider = "ollama"          # or sentence_transformer, gemini, openai
model = "nomic-embed-text"
Enter fullscreen mode Exit fullscreen mode

Numbers

  • 3,150+ tests, 68% coverage
  • v2.25.0, production-stable since v2.10
  • 11 memory types, 24 synapse types, schema v20
  • Python 3.11+, async via aiosqlite
  • MIT license
  • Dashboard: FastAPI + React web UI for visualization

Links

Neural Memory is open source and contributions are welcome. The spreading activation approach is particularly interesting if you've worked with cognitive architectures (ACT-R, Soar) — it's the same theoretical foundation applied to AI agent memory.

Top comments (0)