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

The brain and config at ~/.neuralmemory/ are auto-created on first use.

2. Install the OpenClaw Plugin (Recommended)

The plugin occupies the exclusive memory slot — auto-injects context before each agent run and auto-captures memories after.

CODEBLOCK1

Add to ~/.openclaw/openclaw.json:

CODEBLOCK2

Plugin features:

• - 6 tools registered automatically (nmemremember, nmemrecall, nmemcontext, nmemtodo, nmemstats, nmemhealth)
• INLINECODE2 hook: injects tool instructions + relevant memories as context (persists across /new)
• INLINECODE4 hook: auto-extracts facts, decisions, and TODOs from the conversation
• Configurable: contextDepth (0-3), maxContextTokens (100-10000)

After installing, build the plugin:

CODEBLOCK3

This compiles TypeScript to JavaScript in dist/. The plugin entry point is dist/index.js.

Windows Installation

On Windows, use forward slashes or escaped backslashes in openclaw.json paths:

CODEBLOCK4

To find the installed path:

CODEBLOCK5

If openclaw plugins list doesn't show the plugin:

1. 1. Verify the path in openclaw.json points to the package root (where package.json is)
2. Ensure npm run build was run (the dist/ folder must exist with compiled .js files)
3. Use python instead of python3 in the plugin config (Windows default)

Alternative: MCP Configuration (Manual)

If you prefer MCP over the plugin, add to ~/.openclaw/mcp.json:

CODEBLOCK6

On Windows, use "python" (not "python3"). This gives you all 56 MCP tools but without the auto-context/auto-capture hooks.

3. Verify

CODEBLOCK7

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

Troubleshooting

Symptom	Cause	Fix
INLINECODE21 doesn't show plugin	Plugin path wrong or not built	Run npm run build, verify path in INLINECODE23
Agent runs nmem remember in terminal

Agent confused CLI vs tool | Plugin now auto-injects tool instructions via systemPrompt | | Agent forgets tools after /new | No tool instructions in new session | Plugin now injects systemPrompt on every before_agent_start | | python3 not found (Windows) | Windows uses python not python3 | Set pythonPath: "python" in plugin config | | Timeout errors | Slow machine or large brain | Increase timeout in plugin config (max 120000ms) |

Tools Reference

Core Memory Tools

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

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
INLINECODE38	Auto-extract memories from text	After important conversations — captures decisions, errors, TODOs automatically
INLINECODE39 (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
INLINECODE41	Brain health diagnostics	Periodic checkup, before sharing brain
INLINECODE42

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

CODEBLOCK8

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 INLINECODE52
• No data is sent to external services (unless optional embedding provider is configured)
• Brain isolation: each brain is independent, no cross-contamination
• INLINECODE53 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