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": [""]
    },
    "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 
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//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

Tools Reference

Core Memory Tools

Intelligence Tools

Management Tools

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

1. 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. Call nmem_auto with action="process" on important conversation segments
2. 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

Notes

• Memories are stored locally in SQLite at ~/.neuralmemory/brains/.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