Neuroplastic Memory

Memória inspirada biologicamente para Claude. Plasticidade hebbiana, ciclos de sonho e decaimento temporal para síntese persistente de conhecimento.

GitHub

Documentação

claude-brain

Um sistema de memória persistente inspirado na biologia para LLMs, modelado com base em neuroplasticidade, consolidação e sono.

Mind extrai conceitos de conversas, conecta-os em um grafo de conhecimento persistente e executa ciclos de sonho que consolidam memórias importantes, descobrem associações novas e sinalizam contradições — da mesma forma que o sono NREM e REM molda a memória humana.

[!NOTE] Este é um projeto de fim de semana, vibe-coded com Claude. É um protótipo funcional e um playground para ideias na interseção entre neurociência e memória de LLMs. Não é software de produção. Espere arestas a aparar. Contribuições são bem-vindas.

Arquitetura

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

Início 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

Adicione o servidor MCP à sua configuração do 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"
      }
    }
  }
}

Depois, no 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

Usando Memória em Todas as Conversas

O grafo de memória persiste globalmente em ~/.neuroplastic-memory/, então funciona em qualquer chat ou projeto. Para que o Claude o use automaticamente, vá em Configurações → Geral e adicione o seguinte às suas Preferências Pessoais:

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.

Isso dá a você uma memória compartilhada única em todas as conversas. Para manter a memória isolada em um projeto específico, adicione as mesmas instruções às Instruções do Projeto desse projeto, em vez das suas preferências globais.

Subsistemas

1. Pipeline de Consolidação

Transforma texto bruto em conhecimento de grafo. Um LLM extrai conceitos e relacionamentos (com sinais de afeto — o quanto o usuário enfatizou cada ideia). Cada conceito é incorporado em um vetor denso, verificado contra nós existentes para deduplicação e integrado ao grafo. Um decaimento temporal exponencial é aplicado a cada aresta: conexões ativadas recentemente sobrevivem, as obsoletas são podadas. Isso é plasticidade hebbiana — conexões que disparam juntas se fortalecem, e conexões que não disparam são esquecidas.

2. Sistema de Avaliação

Cada novo conceito é pontuado em quatro canais antes de entrar no grafo:

Canal	Sinal	Mecanismo
Salência	Densidade de engajamento, frequência de perguntas, marcadores de primeira pessoa ("Eu acredito", "Eu preciso"), excitação (exclamação, maiúsculas, palavras fortes), ênfase do usuário vinda do LLM	Pontuação comportamental — o que o usuário se importa, não apenas o que ele disse
Novidade	Distância de cosseno para os nós existentes mais próximos	Distância no espaço de embeddings — ideias genuinamente novas pontuam mais alto
Relevância para objetivos	Similaridade de cosseno com embeddings de objetivos ativos	Conceitos alinhados com objetivos declarados são priorizados
Frequência	Contagem de acesso em escala logarítmica relativa ao nó mais acessado	Conceitos recuperados com frequência são tratados como mais importantes

Esses fatores se combinam em um único score de consolidação (soma ponderada, configurável) que determina a aptidão de sobrevivência de um nó — a probabilidade de ser reproduzido durante o NREM e de resistir ao decaimento.

Impulso de conflito: Se um conceito cair perto de arestas contradicts existentes, a salência recebe um impulso aditivo de +0.3 que pode elevar o score para 1.0 independentemente de outros sinais. Isso modela uma sobreposição semelhante à adrenalina — informações contraditórias disparam alerta imediato, garantindo que não se percam pelo decaimento antes que a fase de simulação de ameaças possa sinalizá-las.

3. Motor de Sonhos

Processamento offline modelado na neurociência do sono. Quatro fases são executadas em sequência:

NREM (reprodução de ondas lentas): Nós de alta salência são reproduzidos e os pesos de suas arestas são fortalecidos, imitando a reprodução hipocampal-cortical observada no sono de ondas lentas. Arestas abaixo do limiar de poda são removidas.

REM (exploração criativa): Caminhadas aleatórias enviesadas a partir de nós-semente percorrem o grafo. A cada passo, o caminhante pode saltar para um nó semanticamente semelhante, mas topologicamente distante — teletransporte criativo. Quando dois nós em uma caminhada são semelhantes em embedding, mas não compartilham aresta, uma conexão provisória é proposta.

Avaliação em vigília: Arestas provisórias são reavaliadas com um limiar mais rigoroso. Apenas conexões que sobrevivem a essa barreira são promovidas a arestas dream_connection reais no grafo. Isso evita que associações alucinadas poluam a base de conhecimento.

Simulação de ameaças: Examina nós de alta confiança em busca de arestas contradicts próximas e as sinaliza. Esses alertas de contradição trazem à tona informações conflitantes que podem precisar de resolução.

4. Sistema de Objetivos

Usuários podem declarar objetivos ("entender X", "investigar Y"). Cada objetivo é incorporado e persistido. Durante a consolidação, cada novo conceito é pontuado quanto à relevância em relação aos objetivos ativos — conceitos alinhados com o que você está tentando aprender são priorizados para consolidação e sobrevivência. Os objetivos são gerenciados pela ferramenta MCP memory_goals e armazenados em goals.json junto ao grafo.

5. Grafo de Conhecimento

Um grafo direcionado baseado em NetworkX com arestas tipadas (causes, contradicts, part_of, dream_connection, goal_linked, related_to). Cada nó carrega seu embedding, scores de avaliação, contagem de acesso, timestamps e metadados. O grafo persiste em JSON e suporta busca por similaridade via distância de cosseno sobre embeddings.

Ferramentas MCP

Ferramenta	Descrição
`memory_store`	Ingerir texto de conversa — extrai conceitos e relacionamentos via Claude
`memory_retrieve`	Consultar o grafo — retorna contexto formatado com conexões inline
`memory_dream`	Executar um ciclo de sonho completo (NREM + REM + vigília + ameaça)
`memory_dream_report`	Narrativa legível por humanos do último ciclo de sonho
`memory_goals`	Gerenciar objetivos de pesquisa — adicionar, listar ou remover
`memory_status`	Estatísticas do grafo (contagens de nós/arestas, distribuições de scores)
`memory_stats_detailed`	Detalhamento de avaliação por nó, principais arestas, contradições, arestas de sonho
`memory_tune`	Ajustar parâmetros em tempo de execução (ex.: `dream.rem_jump_probability`)

Visualização 3D

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

Abra http://localhost:8080 para um grafo 3D interativo com direcionamento por força.

Nós são dimensionados pelo score de consolidação.

Cor do nó	Origem
Azul	`conversation` — extraído de texto ingerido
Roxo	`dream` — criado durante ciclos de sonho
Verde	`consolidation` — criado durante a consolidação
Laranja	`query` — registrado a partir de consultas de recuperação

Arestas são mais espessas para pesos maiores. Partículas animadas aparecem em arestas com peso > 0.5.

Cor da aresta	Tipo de relacionamento
Cinza	`related_to`
Azul	`causes`
Dourado	`dream_connection`
Vermelho	`contradicts`
Cinza escuro	`part_of`
Verde suave	`goal_linked`

Controles: Atualizar, Atualização automática (30s), Reproduzir Sonho (reproduz caminhos de caminhada com marcadores de salto), Controle deslizante de velocidade. Passe o mouse sobre qualquer nó para ver seu rótulo, origem e scores.

Configuração

Todos os parâmetros são ajustáveis em tempo de execução via memory_tune ou em src/mind/schemas/config.py:

Pesos de avaliação: alpha/beta/gamma/delta (0.25 cada) — equilibram salência, novidade, relevância para objetivos e frequência de recuperação no score de consolidação.

Sub-pesos de salência: salience_engagement_weight (0.2), salience_question_weight (0.2), salience_personal_weight (0.3), salience_arousal_weight (0.3) — controlam quais sinais comportamentais impulsionam a salência.

Parâmetros de sonho: rem_jump_probability (0.3), rem_walk_steps (10), rem_seed_count (5), waking_threshold (0.35), nrem_salience_threshold (0.3)

Consolidação: decay_constant (0.01), novelty_threshold (0.7)

Persistência

Arquivo	Localização
Grafo de conhecimento	`~/.neuroplastic-memory/graph.json`
Relatórios de sonho	`~/.neuroplastic-memory/last_dream_report.json`
Objetivos	`~/.neuroplastic-memory/goals.json`

Testes

PYTHONPATH=src uv run pytest tests/ -v

161 testes cobrindo pontuação de avaliação, pipeline de consolidação, fases de sonho, operações de grafo, persistência de objetivos, metadados de afeto, ferramentas MCP e integração.