neural-memory

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

pip install neural-memory

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.

# Install from npm
npm install -g neuralmemory

Add to ~/.openclaw/openclaw.json:

{
  "plugins": {
    "load": {
      "paths": ["<path-to-installed-plugin>"]
    },
    "entries": {
      "neuralmemory": {
        "enabled": true,
        "config": {
          "pythonPath": "python",
          "brain": "default",
          "autoContext": true,
          "autoCapture": true
        }
      }
    },
    "slots": {
      "memory": "neuralmemory"
    }
  }
}

Plugin features:

• 6 tools registered automatically (nmem_remember, nmem_recall, nmem_context, nmem_todo, nmem_stats, nmem_health)
• before_agent_start hook: injects tool instructions + relevant memories as context (persists across /new)
• agent_end hook: auto-extracts facts, decisions, and TODOs from the conversation
• Configurable: contextDepth (0-3), maxContextTokens (100-10000)

After installing, build the plugin:

cd <path-to-installed-plugin>
npm run build

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:

{
  "plugins": {
    "load": {
      "paths": ["C:/Users/<you>/AppData/Roaming/npm/node_modules/neuralmemory"]
    }
  }
}

To find the installed path:

npm list -g neuralmemory --parseable

If openclaw plugins list doesn't show the plugin:

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:

{
  "mcpServers": {
    "neural-memory": {
      "command": "python",
      "args": ["-m", "neural_memory.mcp"],
      "env": {
        "NEURALMEMORY_BRAIN": "default"
      }
    }
  }
}

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

3. Verify

nmem stats

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

Troubleshooting

Symptom	Cause	Fix
openclaw plugins list doesn't show plugin	Plugin path wrong or not built	Run npm run build, verify path in openclaw.json
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
nmem_remember	Store a memory	After decisions, errors, facts, insights, user preferences
nmem_recall	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
nmem_auto	Auto-extract memories from text	After important conversations — captures decisions, errors, TODOs automatically
nmem_recall (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
nmem_health	Brain health diagnostics	Periodic checkup, before sharing brain
nmem_stats	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. 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

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

At Session End

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

Examples

Remember a decision

nmem_remember(
  content="Use PostgreSQL for production, SQLite for development",
  type="decision",
  tags=["database", "infrastructure"],
  priority=8
)

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 CAUSED_BY and LEADS_TO 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 (CAUSED_BY/LEADS_TO), semantic (IS_A/HAS_PROPERTY), 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 ~/.neuralmemory/brains/<brain>.db
• No data is sent to external services (unless optional embedding provider is configured)
• Brain isolation: each brain is independent, no cross-contamination
• nmem_remember 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