Neuroplastic Memory

Memoria inspirada biológicamente para Claude. Plasticidad hebbiana, ciclos de sueño y decaimiento temporal para la síntesis persistente de conocimiento.

GitHubPrueba este MCPPatrocinado

Documentación

claude-brain

Un sistema de memoria persistente inspirado en la biología para LLMs, modelado según la neuroplasticidad, la consolidación y el sueño.

Mind extrae conceptos de las conversaciones, los conecta en un grafo de conocimiento persistente y ejecuta ciclos de sueño que consolidan recuerdos importantes, descubren asociaciones novedosas y señalan contradicciones, de la misma manera en que el sueño NREM y REM moldean la memoria humana.

[!NOTE] Este es un proyecto de fin de semana, codificado con Claude. Es un prototipo funcional y un campo de juego para ideas en la intersección de la neurociencia y la memoria de LLMs. No es software de producción. Espera bordes ásperos. Contribuciones bienvenidas.

Arquitectura

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

Inicio rápido

# 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

Agrega el servidor MCP a tu configuración de Claude Desktop (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"
      }
    }
  }
}

Luego en 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

Usar memoria en todas las conversaciones

El grafo de memoria persiste globalmente en ~/.neuroplastic-memory/, por lo que funciona en cualquier chat o proyecto. Para que Claude lo use automáticamente, ve a Configuración → General y agrega lo siguiente a tus Preferencias personales:

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.

Esto te da una memoria compartida única en todas las conversaciones. Para mantener la memoria aislada a un proyecto específico, agrega las mismas instrucciones a las Instrucciones del proyecto de ese proyecto en lugar de tus preferencias globales.

Subsistemas

1. Pipeline de consolidación

Convierte texto crudo en conocimiento de grafo. Un LLM extrae conceptos y relaciones (con señales de afecto: cuán fuertemente enfatizó el usuario cada idea). Cada concepto se incrusta en un vector denso, se verifica contra nodos existentes para deduplicación y se integra en el grafo. Una decadencia temporal exponencial se ejecuta en cada borde: las conexiones activadas recientemente sobreviven, las obsoletas se podan. Esto es plasticidad hebbiana: las conexiones que se disparan juntas se conectan juntas, y las que no se olvidan.

2. Sistema de evaluación

Cada nuevo concepto se puntúa en cuatro canales antes de entrar al grafo:

Canal	Señal	Mecanismo
Relevancia	Densidad de participación, frecuencia de preguntas, marcadores de primera persona ("creo", "necesito"), excitación (exclamación, mayúsculas, palabras fuertes), énfasis del usuario del LLM	Puntuación conductual: lo que le importa al usuario, no solo lo que dijo
Novedad	Distancia coseno a los nodos existentes más cercanos	Distancia en el espacio de incrustación: las ideas genuinamente nuevas puntúan más alto
Relevancia de objetivo	Similitud coseno con incrustaciones de objetivos activos	Los conceptos alineados con objetivos declarados se priorizan
Frecuencia	Conteo de acceso escalado logarítmicamente relativo al nodo más accedido	Los conceptos recuperados con frecuencia se tratan como más importantes

Estos se combinan en una única puntuación de consolidación (suma ponderada, configurable) que determina la aptitud de supervivencia de un nodo: cuán probable es que se reproduzca durante NREM y que resista la decadencia.

Impulso de conflicto: Si un concepto aterriza cerca de bordes contradicts existentes, la relevancia recibe un impulso aditivo de +0.3 que puede llevar la puntuación a 1.0 independientemente de otras señales. Esto modela una anulación similar a la adrenalina: la información contradictoria desencadena alerta inmediata, asegurando que no se pierda por decadencia antes de que la fase de simulación de amenaza pueda señalarla.

3. Motor de sueños

Procesamiento fuera de línea modelado según la neurociencia del sueño. Cuatro fases se ejecutan en secuencia:

NREM (reproducción de onda lenta): Los nodos de alta relevancia se reproducen y sus pesos de borde se fortalecen, imitando la reproducción hipocampal-cortical observada en el sueño de onda lenta. Los bordes por debajo de un umbral de poda se eliminan.

REM (exploración creativa): Caminatas aleatorias sesgadas desde nodos semilla atraviesan el grafo. En cada paso, el caminante puede saltar a un nodo semánticamente similar pero topológicamente distante: teletransportación creativa. Cuando dos nodos en una caminata son similares en incrustación pero no comparten borde, se propone una conexión provisional.

Evaluación de vigilia: Los bordes provisionales se reevalúan con un umbral más estricto. Solo las conexiones que sobreviven esta puerta se promueven a bordes dream_connection reales en el grafo. Esto evita que asociaciones alucinadas contaminen la base de conocimiento.

Simulación de amenaza: Escanea nodos de alta confianza en busca de bordes contradicts cercanos y los señala. Estas alertas de contradicción sacan a la superficie información conflictiva que puede necesitar resolución.

4. Sistema de objetivos

Los usuarios pueden declarar objetivos ("entender X", "investigar Y"). Cada objetivo se incrusta y persiste. Durante la consolidación, cada nuevo concepto se puntúa por relevancia contra objetivos activos: los conceptos alineados con lo que intentas aprender se priorizan para consolidación y supervivencia. Los objetivos se gestionan a través de la herramienta MCP memory_goals y se almacenan en goals.json junto al grafo.

5. Grafo de conocimiento

Un grafo dirigido respaldado por NetworkX con bordes tipados (causes, contradicts, part_of, dream_connection, goal_linked, related_to). Cada nodo lleva su incrustación, puntuaciones de evaluación, conteo de acceso, marcas de tiempo y metadatos. El grafo persiste a JSON y admite búsqueda de similitud mediante distancia coseno sobre incrustaciones.

Herramientas MCP

Herramienta	Descripción
`memory_store`	Ingerir texto de conversación: extrae conceptos y relaciones mediante Claude
`memory_retrieve`	Consultar el grafo: devuelve contexto formateado con conexiones en línea
`memory_dream`	Ejecutar un ciclo de sueño completo (NREM + REM + vigilia + amenaza)
`memory_dream_report`	Narrativa legible por humanos del último ciclo de sueño
`memory_goals`	Gestionar objetivos de investigación: agregar, listar o eliminar
`memory_status`	Estadísticas del grafo (conteos de nodos/bordes, distribuciones de puntuación)
`memory_stats_detailed`	Desglose detallado de evaluación por nodo, bordes principales, contradicciones, bordes de sueño
`memory_tune`	Ajustar parámetros en tiempo de ejecución (p. ej., `dream.rem_jump_probability`)

Visualización 3D

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

Abre http://localhost:8080 para un grafo 3D interactivo de fuerza dirigida.

Los nodos se dimensionan según la puntuación de consolidación.

Color de nodo	Origen
Azul	`conversation` — extraído de texto ingerido
Púrpura	`dream` — creado durante ciclos de sueño
Verde	`consolidation` — creado durante consolidación
Naranja	`query` — registrado desde consultas de recuperación

Los bordes son más gruesos para mayor peso. Partículas animadas aparecen en bordes con peso > 0.5.

Color de borde	Tipo de relación
Gris	`related_to`
Azul	`causes`
Dorado	`dream_connection`
Rojo	`contradicts`
Gris oscuro	`part_of`
Verde apagado	`goal_linked`

Controles: Actualizar, Auto-actualizar (30s), Reproducir sueño (reproduce rutas de caminata con marcadores de salto), Control deslizante de velocidad. Pasa el cursor sobre cualquier nodo para ver su etiqueta, origen y puntuaciones.

Configuración

Todos los parámetros son ajustables en tiempo de ejecución mediante memory_tune o en src/mind/schemas/config.py:

Pesos de evaluación: alpha/beta/gamma/delta (0.25 cada uno) — equilibra relevancia, novedad, relevancia de objetivo y frecuencia de recuperación en la puntuación de consolidación.

Sub-pesos de relevancia: salience_engagement_weight (0.2), salience_question_weight (0.2), salience_personal_weight (0.3), salience_arousal_weight (0.3) — controla qué señales conductuales impulsan la relevancia.

Parámetros de sueño: rem_jump_probability (0.3), rem_walk_steps (10), rem_seed_count (5), waking_threshold (0.35), nrem_salience_threshold (0.3)

Consolidación: decay_constant (0.01), novelty_threshold (0.7)

Persistencia

Archivo	Ubicación
Grafo de conocimiento	`~/.neuroplastic-memory/graph.json`
Informes de sueño	`~/.neuroplastic-memory/last_dream_report.json`
Objetivos	`~/.neuroplastic-memory/goals.json`

Pruebas

PYTHONPATH=src uv run pytest tests/ -v

161 pruebas que cubren puntuación de evaluación, pipeline de consolidación, fases de sueño, operaciones de grafo, persistencia de objetivos, metadatos de afecto, herramientas MCP e integración.