NeuralMemory

Reflex-based memory system for AI agents
Retrieval through activation, not search

---

What is NeuralMemory?

NeuralMemory stores experiences as interconnected neurons and recalls them through spreading activation - mimicking how the human brain works. Instead of searching a database, memories are retrieved through associative recall.

# Store a memory
nmem remember "Fixed auth bug with null check in login.py:42"

# Recall through association
nmem recall "auth bug fix"
# → "Fixed auth bug with null check in login.py:42"

Why Not RAG / Vector Search?

Aspect	RAG / Vector Search	NeuralMemory
Model	Search Engine	Human Brain
LLM/Embedding	Required (embedding API calls)	None — pure algorithmic graph traversal
Query	"Find similar text"	"Recall through association"
Structure	Flat chunks + embeddings	Neural graph + synapses
Relationships	None (just similarity)	Explicit: CAUSED_BY, LEADS_TO
Temporal	Timestamp filter	Time as first-class neurons
Multi-hop	Multiple queries needed	Natural graph traversal
API Cost	~$0.02/1K queries	$0.00 — fully offline

Example: Causal Query

Query: "Why did Tuesday's outage happen?"

• RAG: Returns "JWT caused outage" (missing why we used JWT)
• NeuralMemory: Traces outage ← CAUSED_BY ← JWT ← SUGGESTED_BY ← Alice → full causal chain

The Problem

AI agents face fundamental memory limitations:

Problem	Impact
Limited context windows	Cannot complete large projects across sessions
Session amnesia	Forget everything between conversations
No knowledge sharing	Cannot share learned patterns with other agents
Context overflow	Important early context gets lost

The Solution

Feature	Benefit
Persistent memory	Survives across sessions
Efficient retrieval	Inject only relevant context, not everything
Shareable brains	Export/import patterns like Git repos
Real-time sharing	Multi-agent collaboration
Project-bounded	Optimize for active project timeframes

Quick Start

Installation

pip install neural-memory

With optional features:

pip install neural-memory[server]   # FastAPI server + Web UI
pip install neural-memory[nlp-vi]   # Vietnamese NLP
pip install neural-memory[all]      # All features

Basic Usage

CLIPythonMCP Server

# Store memories
nmem remember "Fixed auth bug with null check in login.py:42"
nmem remember "We decided to use PostgreSQL" --type decision
nmem todo "Review PR #123" --priority 7

# Query memories
nmem recall "auth bug"
nmem recall "database decision" --depth 2

# Get context for AI injection
nmem context --limit 10 --json

import asyncio
from neural_memory import Brain
from neural_memory.storage import InMemoryStorage
from neural_memory.engine.encoder import MemoryEncoder
from neural_memory.engine.retrieval import ReflexPipeline

async def main():
    storage = InMemoryStorage()
    brain = Brain.create("my_brain")
    await storage.save_brain(brain)
    storage.set_brain(brain.id)

    # Encode memories
    encoder = MemoryEncoder(storage, brain.config)
    await encoder.encode("Met Alice to discuss API design")

    # Query through activation
    pipeline = ReflexPipeline(storage, brain.config)
    result = await pipeline.query("What did we discuss?")
    print(result.context)

asyncio.run(main())

// ~/.claude/mcp_servers.json
{
  "neural-memory": {
    "command": "nmem-mcp"
  }
}

Claude will have access to:

• nmem_remember - Store memories
• nmem_recall - Query memories
• nmem_context - Get recent context
• nmem_todo - Quick TODO
• nmem_stats - Brain statistics
• nmem_auto - Auto-capture memories
• nmem_train_db - Train brain from database schema
• nmem_alerts - View and manage brain health alerts
• nmem_sync - Multi-device sync

VS Code Extension

Install the NeuralMemory extension for a visual brain explorer directly in your editor:

• Memory Tree View — Browse neurons grouped by type in the activity bar
• Graph Explorer — Interactive Cytoscape.js force-directed graph
• CodeLens — Memory counts on functions/classes, comment trigger detection
• Encode & Recall — Store and query memories from the command palette
• Real-time Sync — WebSocket updates for tree, graph, and status bar

cd vscode-extension && npm run build
# Install from .vsix or use Extension Developer Host

Web UI Visualization

Start the server and access the interactive brain visualization:

pip install neural-memory[server]
nmem serve
# Open http://localhost:8000/ui

Features

• Reflex Activation - Trail-based retrieval through fiber pathways with conductivity (v0.6.0+)
• Co-Activation - Hebbian binding detects neurons activated by multiple sources (v0.6.0+)
• Time-First Anchoring - Time neurons as primary anchors for temporally-aware recall (v0.6.0+)
• Spreading Activation - Neural graph-based retrieval (classic mode)
• Multi-language - English + Vietnamese support
• Typed Memories - fact, decision, todo, insight, etc.
• Priority System - 0-10 priority levels
• Expiry/TTL - Auto-expire temporary memories
• Project Scoping - Organize memories by project
• Sensitive Content Detection - Auto-detect secrets, PII
• Memory Decay - Ebbinghaus forgetting curve
• Brain Sharing - Export, import, merge brains
• DB-to-Brain Training - Teach brains to understand database schemas (v1.6.0+)
• AI Agent Skills - Composable memory-intake, memory-audit, memory-evolution workflows (v1.6.0+)
• Smart Context Optimizer - 5-factor composite scoring + SimHash dedup + token budgeting (v2.6.0+)
• Proactive Alerts - Persistent brain health alerts with lifecycle management (v2.6.0+)
• Recall Pattern Learning - Topic co-occurrence mining + follow-up suggestions (v2.6.0+)
• Adaptive Recall - Bayesian depth priors that learn optimal retrieval depth per entity (v2.8.0+)
• Tiered Memory Compression - Age-based compression preserving entity graph structure (v2.8.0+)
• Multi-Device Sync - Hub-and-spoke incremental sync with neural-aware conflict resolution (v2.8.0+)

Next Steps

• Installation

  ---

  Install NeuralMemory and get started in minutes

  Install

• Quick Start

  ---

  Learn the basics with a hands-on tutorial

  Quick Start

• Concepts

  ---

  Understand how NeuralMemory works

  Concepts

• Integration

  ---

  Integrate with Claude, Cursor, and other tools

  Integration

• FAQ

  ---

  Common questions, architecture, and honest limitations

  FAQ

• Benchmarks

  ---

  Reproducible performance measurements

  Benchmarks