NeuralMemory — Associative Memory for AI Agents

A biologically-inspired memory system that uses spreading activation instead of keyword/vector search. Memories form a neural graph where neurons connect via 20 typed synapses. Frequently co-accessed memories strengthen their connections (Hebbian learning). Stale memories decay naturally. Contradictions are auto-detected.

Why not just vector search? Vector search finds documents similar to your query. NeuralMemory finds conceptually related memories through graph traversal — even when there's no keyword or embedding overlap. "What decision did we make about auth?" activates time + entity + concept neurons simultaneously and finds the intersection.

Setup

1. Install NeuralMemory

CODEBLOCK0

This creates ~/.neuralmemory/ with a default brain and configures MCP automatically.

2. Configure MCP for OpenClaw

Add to your OpenClaw MCP configuration (~/.openclaw/mcp.json or project openclaw.json):

CODEBLOCK1

3. Verify

CODEBLOCK2

You should see brain statistics (neurons, synapses, fibers).

Tools Reference

Core Memory Tools

Tool	Purpose	When to Use
INLINECODE3	Store a memory	After decisions, errors, facts, insights, user preferences
INLINECODE4

Query memories | Before tasks, when user references past context, "do you remember..." | | nmem_context | Get recent memories | At session start, inject fresh context | | nmem_todo | Quick TODO with 30-day expiry | Task tracking |

Intelligence Tools

Tool	Purpose	When to Use
INLINECODE7	Auto-extract memories from text	After important conversations — captures decisions, errors, TODOs automatically
INLINECODE8 (depth=3)

Deep associative recall | Complex questions requiring cross-domain connections | | nmem_habits | Workflow pattern suggestions | When user repeats similar action sequences |

Management Tools

Tool	Purpose	When to Use
INLINECODE10	Brain health diagnostics	Periodic checkup, before sharing brain
INLINECODE11

Brain statistics | Quick overview of memory counts | | nmem_version | Brain snapshots and rollback | Before risky operations, version checkpoints | | nmem_transplant | Transfer memories between brains | Cross-project knowledge sharing |

Workflow

At Session Start

1. 1. Call nmem_context to inject recent memories into your awareness
2. If user mentions a specific topic, call nmem_recall with that topic

During Conversation

1. 3. When a decision is made: nmem_remember with type="decision"
2. When an error occurs: nmem_remember with type="error"
3. When user states a preference: nmem_remember with type="preference"
4. When asked about past events: nmem_recall with appropriate depth

At Session End

1. 7. Call nmem_auto with action="process" on important conversation segments
2. This auto-extracts facts, decisions, errors, and TODOs

Examples

Remember a decision

CODEBLOCK3

Recall with spreading activation

nmem_recall(
  query="database configuration for production",
  depth=1,
  max_tokens=500
)

Returns memories found via graph traversal, not keyword matching. Related memories (e.g., "deploy uses Docker with pg_dump backups") surface even without shared keywords.

Trace causal chains

nmem_recall(
  query="why did the deployment fail last week?",
  depth=2
)

Follows CAUSEDBY and LEADSTO synapses to trace cause-and-effect chains.

Auto-capture from conversation

nmem_auto(
  action="process",
  text="We decided to switch from REST to GraphQL because the frontend needs flexible queries. The migration will take 2 sprints. TODO: update API docs."
)

Automatically extracts: 1 decision, 1 fact, 1 TODO.

Key Features

• - Zero LLM dependency — Pure algorithmic: regex, graph traversal, Hebbian learning
• Spreading activation — Associative recall through neural graph, not keyword/vector search
• 20 synapse types — Temporal (BEFORE/AFTER), causal (CAUSEDBY/LEADSTO), semantic (ISA/HASPROPERTY), emotional (FELT/EVOKES), conflict (CONTRADICTS)
• Memory lifecycle — Short-term → Working → Episodic → Semantic with Ebbinghaus decay
• Contradiction detection — Auto-detects conflicting memories, deprioritizes outdated ones
• Hebbian learning — "Neurons that fire together wire together" — memory improves with use
• Temporal reasoning — Causal chain traversal, event sequences, temporal range queries
• Brain versioning — Snapshot, rollback, diff brain state
• Brain transplant — Transfer filtered knowledge between brains
• Vietnamese + English — Full bilingual support for extraction and sentiment

Depth Levels

Depth	Name	Speed	Use Case
0	Instant	<10ms	Quick facts, recent context
1

Context | ~50ms | Standard recall (default) | | 2 | Habit | ~200ms | Pattern matching, workflow suggestions | | 3 | Deep | ~500ms | Cross-domain associations, causal chains |

Notes

• - Memories are stored locally in SQLite at INLINECODE21
• No data is sent to external services (unless optional embedding provider is configured)
• Brain isolation: each brain is independent, no cross-contamination
• INLINECODE22 returns fiber_id for reference tracking
• Priority scale: 0 (trivial) to 10 (critical), default 5
• Memory types: fact, decision, preference, todo, insight, context, instruction, error, workflow, reference