claude-brain

A biologically-inspired persistent memory system for LLMs, modeled on neuroplasticity, consolidation, and sleep.

Mind extracts concepts from conversations, connects them into a persistent knowledge graph, and runs dream cycles that consolidate important memories, discover novel associations, and flag contradictions — the same way NREM and REM sleep shape human memory.

>[!NOTE]

>This is a weekend project, vibe-coded with Claude. It's a working prototype and a playground for ideas at the intersection of neuroscience and LLM memory. This is not production software. Expect rough edges. Contributions welcome.

Architecture

flowchart TB
    Input(["Conversation Text"]) --> Consolidation

    subgraph Consolidation["Consolidation Pipeline"]
        direction LR
        Extract["LLM Extraction
        + Affect Signals"] --> Embed["Sentence
        Embedding"] --> Dedup["Deduplication
        + Temporal Decay"]
    end

    Consolidation --> Appraisal
    Goals(["Goals"]) -.-> Appraisal

    subgraph Appraisal["Appraisal System"]
        direction LR
        S["Engagement
        Questions
        Personal Stake
        Arousal"] --> Score["Consolidation
        Score"]
        N["Novelty"] --> Score
        F["Frequency"] --> Score
        G["Goal
        Relevance"] --> Score
    end

    Appraisal --> KG

    subgraph KG["Knowledge Graph"]
        Nodes["Concept Nodes"]  Edges["Relationship Edges"]
    end

    KG  Dream

    subgraph Dream["Dream Engine"]
        direction LR
        NREM["NREM
        Replay"] --> REM["REM
        Walks"] --> Wake["Waking
        Gate"] --> Threat["Threat
        Simulation"]
    end

    Query(["Query"]) --> KG
    KG --> Results(["Ranked Results"])

    style Consolidation fill:#d4f0da,stroke:#44cc66,color:#000
    style Appraisal fill:#d4e4ff,stroke:#4488ff,color:#000
    style KG fill:#e8e8e8,stroke:#888,color:#000
    style Dream fill:#ecd4f4,stroke:#aa55dd,color:#000

    style Input fill:#4488ff,stroke:#4488ff,color:#fff
    style Query fill:#ff8833,stroke:#ff8833,color:#fff
    style Results fill:#ff8833,stroke:#ff8833,color:#fff
    style Goals fill:#66aa66,stroke:#66aa66,color:#fff

Quick Start

# Install
git clone https://github.com/gammon-bio/claude-brain && cd claude-brain
uv sync

# Set your Anthropic API key
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env

Add the MCP server to your Claude Desktop config (`claude_desktop_config.json`):

{
  "mcpServers": {
    "neuroplastic-memory": {
      "command": "/absolute/path/to/mind/.venv/bin/python",
      "args": ["-m", "mind"],
      "cwd": "/absolute/path/to/mind",
      "env": {
        "PYTHONPATH": "/absolute/path/to/mind/src"
      }
    }
  }
}

Then in Claude Desktop:

You:    "Store this: [paste conversation or research notes]"
Claude: → calls memory_store → extracts concepts, builds graph

You:    "Run a dream cycle"
Claude: → calls memory_dream → NREM consolidation, REM exploration, threat scan

You:    "What do you remember about X?"
Claude: → calls memory_retrieve → ranked results with connection context

Using Memory Across All Conversations

The memory graph persists globally at `~/.neuroplastic-memory/`, so it works across any chat or project. To have Claude use it automatically, go to Settings → General and add the following to your Personal Preferences:

I use a neuroplastic memory system via MCP tools.
For every conversation:
1. At the START, call memory_retrieve with my first
   message to check for relevant prior context.
2. When I share substantive information — research
   findings, technical decisions, strategic insights,
   project updates — call memory_store with the key
   content. Do not use built-in memory. Use the MCP
   tool memory_store.
3. I may ask you to run memory_dream or
   memory_dream_report at any time.

This gives you a single shared memory across all conversations. To keep memory siloed to a specific project instead, add the same instructions to that project's Project Instructions rather than your global preferences.

Subsystems

1. Consolidation Pipeline

Turns raw text into graph knowledge. An LLM extracts concepts and relationships (with affect signals — how strongly the user emphasized each idea). Each concept is embedded into a dense vector, checked against existing nodes for deduplication, and integrated into the graph. An exponential temporal decay runs on every edge: recently activated connections survive, stale ones are pruned. This is Hebbian plasticity — connections that fire together wire together, and connections that don't are forgotten.

2. Appraisal System

Every new concept is scored across four channels before entering the graph:

These combine into a single consolidation score (weighted sum, configurable) that determines a node's survival fitness — how likely it is to be replayed during NREM and to resist decay.

Conflict boost: If a concept lands near existing `contradicts` edges, salience receives a +0.3 additive boost that can push the score to 1.0 regardless of other signals. This models an adrenaline-like override — contradictory information triggers immediate alerting, ensuring it isn't lost to decay before the threat simulation phase can flag it.

3. Dream Engine

Offline processing modeled on sleep neuroscience. Four phases run in sequence:

NREM (slow-wave replay): High-salience nodes are replayed and their edge weights are strengthened, mimicking the hippocampal-cortical replay observed in slow-wave sleep. Edges below a pruning threshold are removed.

REM (creative exploration): Biased random walks from seed nodes traverse the graph. At each step, the walker may jump to a semantically similar but topologically distant node — creative teleportation. When two nodes on a walk are embedding-similar but share no edge, a provisional connection is proposed.

Waking evaluation: Provisional edges are re-evaluated at a stricter threshold. Only connections that survive this gate are promoted to real `dream_connection` edges in the graph. This prevents hallucinated associations from polluting the knowledge base.

Threat simulation: Scans high-confidence nodes for nearby `contradicts` edges and flags them. These contradiction alerts surface conflicting information that may need resolution.

4. Goal System

Users can declare goals ("understand X", "investigate Y"). Each goal is embedded and persisted. During consolidation, every new concept is scored for relevance against active goals — concepts aligned with what you're trying to learn are prioritized for consolidation and survival. Goals are managed through the `memory_goals` MCP tool and stored in `goals.json` alongside the graph.

5. Knowledge Graph

A NetworkX-backed directed graph with typed edges (`causes`, `contradicts`, `part_of`, `dream_connection`, `goal_linked`, `related_to`). Each node carries its embedding, appraisal scores, access count, timestamps, and metadata. The graph persists to JSON and supports similarity search via cosine distance over embeddings.

MCP Tools

3D Visualization

python3 viz/serve.py [port] [graph_path]
# Defaults: port 8080, graph ~/.neuroplastic-memory/graph.json

Open `http://localhost:8080` for an interactive 3D force-directed graph.

Nodes are sized by consolidation score.

Edges are thicker for higher weight. Animated particles appear on edges with weight > 0.5.

Controls: Refresh, Auto-refresh (30s), Play Dream (replays walk paths with jump markers), Speed slider. Hover any node to see its label, origin, and scores.

Configuration

All parameters are tunable at runtime via `memory_tune` or in `src/mind/schemas/config.py`:

Appraisal weights: `alpha`/`beta`/`gamma`/`delta` (0.25 each) — balance salience, novelty, goal-relevance, and retrieval frequency in the consolidation score.

Salience sub-weights: `salience_engagement_weight` (0.2), `salience_question_weight` (0.2), `salience_personal_weight` (0.3), `salience_arousal_weight` (0.3) — control which behavioral signals drive salience.

Dream parameters: `rem_jump_probability` (0.3), `rem_walk_steps` (10), `rem_seed_count` (5), `waking_threshold` (0.35), `nrem_salience_threshold` (0.3)

Consolidation: `decay_constant` (0.01), `novelty_threshold` (0.7)

Persistence

Tests

PYTHONPATH=src uv run pytest tests/ -v

161 tests covering appraisal scoring, consolidation pipeline, dream phases, graph operations, goal persistence, affect metadata, MCP tools, and integration.