NeuralMemory — Instructions for Claude Code¶

Copy this section into your project's CLAUDE.md or ~/.claude/CLAUDE.md (global).

Memory System¶

This workspace uses NeuralMemory for persistent memory across sessions. You have access to nmem_* MCP tools. Use them proactively — do not wait for the user to ask.

Session Start (ALWAYS do this)¶

nmem_recap()                          # Resume context from last session
nmem_context(limit=20, fresh_only=true)  # Load recent memories
nmem_session(action="get")            # Check current task/feature/progress

If gap_detected: true, run nmem_auto(action="flush", text="<recent context>") to recover lost content.

During Work — REMEMBER automatically¶

Event	Action
Decision made	`nmem_remember(content="...", type="decision", priority=7)`
Bug fixed	`nmem_remember(content="...", type="error", priority=7)`
User preference stated	`nmem_remember(content="...", type="preference", priority=6)`
Important fact learned	`nmem_remember(content="...", type="fact", priority=5)`
TODO identified	`nmem_todo(task="...", priority=6)`
Workflow discovered	`nmem_remember(content="...", type="workflow", priority=6)`

During Work — RECALL before asking¶

Before asking the user a question, check memory first:

nmem_recall(query="<topic>", depth=1)

Depth guide: 0=instant lookup, 1=context (default), 2=patterns, 3=deep graph traversal.

Session End / Before Compaction¶

nmem_auto(action="process", text="<summary of session>")
nmem_session(action="set", feature="...", task="...", progress=0.8)

Before /compact or /new:

nmem_auto(action="flush", text="<recent conversation>")

Project Context¶

nmem_eternal(action="save", project_name="MyProject", tech_stack=["React", "Node.js"])
nmem_eternal(action="save", decision="Use PostgreSQL", reason="Team expertise")

Codebase Indexing¶

First time on a project:

nmem_index(action="scan", path="./src")

Then nmem_recall(query="authentication") finds related code through the neural graph.

Knowledge Base Training¶

Train permanent knowledge from documentation files:

# Train from docs directory (PDF, DOCX, PPTX, HTML, JSON, XLSX, CSV, MD, TXT, RST)
nmem_train(action="train", path="docs/", domain_tag="react")

# Train a single file
nmem_train(action="train", path="api-spec.pdf")

# Check training status
nmem_train(action="status")

Trained knowledge is pinned — permanent, no decay, no pruning. Re-training same file is skipped (SHA-256 dedup).

For non-text formats: pip install neural-memory[extract]

Pin/Unpin Memories¶

nmem_pin(fiber_ids=["id1", "id2"], pinned=true)   # Make permanent
nmem_pin(fiber_ids=["id1"], pinned=false)           # Resume lifecycle

Health & Diagnostics¶

nmem_health()                              # Brain health score + warnings
nmem_stats()                               # Memory counts and freshness
nmem_alerts(action="list")                 # Active health alerts
nmem_conflicts(action="list")              # Conflicting memories
nmem_evolution()                           # Brain maturation + plasticity

Spaced Repetition¶

nmem_review(action="queue")                # Get memories due for review
nmem_review(action="mark", fiber_id="...", success=true)  # Record result

Brain Versioning & Transplant¶

nmem_version(action="create", name="pre-refactor")  # Snapshot
nmem_version(action="rollback", version_id="...")    # Restore
nmem_transplant(source_brain="other", tags=["react"])  # Import from another brain

Multi-Device Sync¶

nmem_sync(action="full")                   # Bi-directional sync with hub
nmem_sync_status()                         # Check sync status
nmem_sync_config(action="set", hub_url="https://hub:8080", enabled=true)

Import External Data¶

nmem_import(source="chromadb", connection="/path/to/chroma")
nmem_import(source="mem0", user_id="user123")

Edit & Forget — Correct Mistakes¶

# Fix wrong type (auto-detector got it wrong)
nmem_edit(memory_id="fiber-abc", type="insight")

# Fix wrong content
nmem_edit(memory_id="fiber-abc", content="Corrected: the bug was in auth.py, not login.py")

# Adjust priority
nmem_edit(memory_id="fiber-abc", priority=9)

# Soft delete — memory decays naturally (recommended for outdated info)
nmem_forget(memory_id="fiber-abc", reason="outdated")

# Hard delete — permanent removal (for sensitive data, test garbage)
nmem_forget(memory_id="fiber-abc", hard=true)

Cognitive Reasoning¶

nmem_hypothesize(action="create", content="Redis is the bottleneck", confidence=0.6)
nmem_evidence(hypothesis_id="h-1", evidence_type="for", content="Redis latency 200ms")
nmem_predict(action="create", content="Fix will drop latency 50%", hypothesis_id="h-1", deadline="2026-04-01")
nmem_verify(prediction_id="p-1", outcome="correct")
nmem_cognitive(action="summary")           # Hot index
nmem_gaps(action="detect", topic="...")    # Track unknowns
nmem_schema(action="evolve", hypothesis_id="h-1", content="...", reason="...")

Connection Tracing¶

nmem_explain(entity_a="Redis", entity_b="auth outage")

Traces shortest path with evidence. Use to debug recall or verify connections.

Rules¶

Be proactive — remember important info without being asked
Store 3-5 memories per task — a bug fix has: root cause, fix, insight, prevention
Use rich language — "Chose X over Y because Z" not just "X". Mix causal, temporal, relational, comparative
Check memory first — recall before asking questions the user may have answered before
Use diverse types — fact, decision, error, preference, todo, workflow, insight, instruction, context
Set priority — critical=7-10, normal=5, trivial=1-3
Add tags — always include project name + topic for better retrieval
Recap on start — always call nmem_recap() at session beginning
Train KB first — if project has docs/, train them into memory for permanent context
Fix mistakes — use nmem_edit for wrong types/content, nmem_forget for outdated info
Health weekly — nmem_health() and fix the highest penalty first