🧠 My-Memory

Transforme qualquer repositório ou vault Markdown em uma memória autoconsciente (Repository Brain) para você e seus Agentes de IA.

💡 Por que o My-Memory?

Agentes de IA (Claude Code, Cursor, Antigravity, GitHub Copilot, Windsurf) sofrem com limites de contexto e alucinações relacionais quando navegam em projetos grandes:

1. Perda de Contexto: Não é viável enviar centenas de arquivos para a janela de contexto sem estourar tokens e aumentar custos.
2. Dependências Quebradas: A IA altera um módulo sem saber quais componentes dependem dele no grafo.
3. Decisões Esquecidas: A IA refatora código ignorando decisões de arquitetura (ADRs) documentadas no passado.

O My-Memory resolve isso unificando busca vetorial, grafo de conhecimento e busca léxica em uma camada unificada de altíssima performance, acessível diretamente via terminal ou pelo Model Context Protocol (MCP).

⚡ Arquitetura em 5 Pilares

                                [ Arquivos Markdown / Notas ]
                                              │
                         ┌────────────────────┴────────────────────┐
                         ▼                                         ▼
             [ Parser [[wikilinks]] & #tags ]            [ Chunking Semântico ]
                         │                                         │
                         ▼                                         ▼
               ( graph_nodes & edges )                  [ Ollama Embeddings ]
                         │                               (nomic-embed-text 768d)
                         │                                         │
                         │                         ┌───────────────┴───────────────┐
                         │                         ▼                               ▼
                         │                 [ sqlite-vec ]                 [ TurboQuant 4-bit ]
                         │                 (float32 k-NN)               (32 Reflexões Householder
                         │                         │                        + Bit-Packing)
                         │                         │                               │
                         ▼                         ▼                               ▼
       ┌───────────────────────────────────────────────────────────────────────────────────────┐
       │                              SQLite Local (memory.db)                                 │
       │  • documents         • chunks_vec (vec0)          • graph_nodes                       │
       │  • chunks            • chunks_turboquant (4-bit)  • graph_edges                       │
       │  • chunks_fts (BM25)                                                                  │
       └───────────────────────────────────────────────────────────────────────────────────────┘
                                                   ▲
                                                   │
                         ┌─────────────────────────┴─────────────────────────┐
                         ▼                                                   ▼
            [ CLI: mem search [-tq] ]                           [ Servidor MCP: mem mcp ]
             (Desenvolvedor no terminal)                           (Claude Code, Cursor, IAs)

1. 📦 SQLite Unificado & PostgreSQL Opcional: Sem dependências pesadas (sem Neo4j, sem Pinecone, sem Elasticsearch). Armazena documentos, tabela virtual sqlite-vec, índice léxico FTS5 (BM25) e conexões de grafo em um arquivo local único ou em PostgreSQL corporativo com pgvector.
2. 🔬 TurboQuant (Google DeepMind, ICLR 2026): Implementação pioneira em Go da quantização de 4-bits com 32 reflexões ortogonais de Householder ($R^T R = I$). Reduz o consumo vetorial em ~88% (de 3.072 para 388 bytes por chunk) mantendo fidelidade $> 99%$.
3. 🕸 Grafo Estilo Obsidian via SQL Recursivo: Extrai conexões explícitas de notas ([[links]] e #tags), permitindo travessias relacionais, detecção de comunidades (LPA) e análise de raio de impacto em microssegundos.
4. 🔌 Model Context Protocol (MCP) Nativo: Conecta-se diretamente aos assistentes de codificação de IA via stdio (JSON-RPC 2.0) ou rede HTTP/SSE, expondo ferramentas de busca e expansão de contexto.
5. 🏛️ Federação, Cofre Central e Wikilinks Cross-Vault: Vincula um Cofre Central de padrões corporativos (Google Drive / OneDrive para Obsidian) a repositórios satélites com repo_id criptográfico imutável, catálogo global (~/.memory/config.yaml), zero-credentials no Git, busca híbrida federada via RRF e protocolo canônico universal memory://<repo>/<path> para resolução transparente de wikilinks cross-vault em editores e MCP.

📊 Eficiência TurboQuant (Google DeepMind, ICLR 2026)

Para um vetor de 768 dimensões (nomic-embed-text):

⚡ Instalação Rápida (1 Comando)

Instale a versão oficial compilada do My-Memory em segundos, com integridade criptográfica SHA-256 verificada e configuração automática de PATH (sem requerer Go instalado):

Windows (PowerShell)

irm https://raw.githubusercontent.com/FelipeMiiller/my-memory/main/scripts/install.ps1 | iex

Linux & macOS (POSIX Shell)

curl -fsSL https://raw.githubusercontent.com/FelipeMiiller/my-memory/main/scripts/install.sh | sh

Opção via Go Toolchain: Se você possui Go $\ge$ 1.22 instalado:

go install github.com/FelipeMiiller/my-memory/cmd/mem@latest

🚀 Início Rápido (Quickstart)

1. Inicializar o Vault no seu Projeto

Na pasta raiz do seu repositório de código ou vault de notas:

mem init

(Gera a pasta .memory/ com repo_id, escopo de pastas, .gitignore seguro e registra no catálogo global).

2. Configurar Cofre Central e Preferências Globais (Opcional)

mem setup

(Assistente interativo que conecta seu Google Drive/OneDrive e grava em ~/.memory/config.yaml).

3. Auto-Configurar Clientes de IA

mem install

(Configura automaticamente Claude Desktop, Cursor, VS Code e Windsurf para se conectarem ao seu vault via MCP).

4. Indexar e Buscar

# Indexar notas com cache incremental SHA-256
mem index

# Busca híbrida federada (Local + Central via RRF)
mem search "como funciona o cache incremental?"

🌐 Visualizador Interativo de Grafo (graph.html)

O My-Memory gera um visualizador interativo de grafo em HTML/SVG standalone (Zero-CDN, sem internet ou dependências de bibliotecas externas). Ele transforma todas as conexões de notas Markdown, [[wikilinks]], tags # e decisões arquiteturais em uma teia visual navegável em tempo real no seu navegador:

🔍 O que a visualização revela:

• Autoridade e Centralidade Estrutural (PageRank & God Nodes): O tamanho dos círculos é proporcional à autoridade estrutural calculada via PageRank Ponderado (ADR-014). Hubs centrais como Wikilinks, ARCHITECTURE, AGENTS, COMO_USAR e CLI_GUIDE emergem naturalmente como referências estruturais do repositório.
• Clusters e Comunidades Semânticas (LPA): As cores dos nós refletem agrupamentos conceituais gerados pelo Label Propagation Algorithm (LPA) ponderado com cálculo de Modularidade Newman-Girvan (ADR-022), revelando subsistemas e domínios de conhecimento interligados.
• Arestas Semânticas & Relações: Linhas direcionadas demonstram fluxos de dependência e referências cruzadas (links_to, tagged_as, dependências técnicas).
• Detecção Visual de Órfãos & Dead Links: Nós periféricos (em tons avermelhados/magenta desconectados) representam notas isoladas ou referências quebradas, funcionando como uma auditoria visual complementar ao mem doctor (ADR-013).
• Inspeção Cirúrgica em 3 Colunas (Triptych Node Inspector - ADR-024): Ao clicar em qualquer nó no gráfico interativo, abre-se um modal retrátil com visão cirúrgica completa:
  1. Coluna 1 (Inbound): Notas e dependentes chamadores classificados por risco e PageRank.
  2. Coluna 2 (Centro): Metadados canônicos, score de Blast Radius e preview de conteúdo seguro.
  3. Coluna 3 (Outbound): Referências de saída com verificação ativa de integridade e atalho para abrir diretamente no Obsidian (obsidian://open?file=...).

🕹️ Como Gerar e Abrir:

# 1. Gerar e abrir automaticamente no navegador padrão
./bin/mem.exe graph view --open

# 2. Exportar para um arquivo HTML específico
./bin/mem.exe export --html graph.html

# 3. Via ferramenta MCP para Agentes de IA
# A tool memory_visualize_graph compila e salva o grafo instantaneamente.

📚 Navegação da Documentação

Para mergulhar nos detalhes operacionais, matemáticos e de integração, consulte os guias dedicados:

🤖 Ferramentas MCP para Assistentes de IA

Quando executado como servidor MCP (mem mcp), o My-Memory disponibiliza 17 ferramentas para o ecossistema de IA:

• memory_search: Busca híbrida (RRF) unificando FTS, vetores e grafo com decaimento temporal opcional.
• memory_get_neighbors: Expansão recursiva de nós e dependências conectadas via SQL recursivo (CTEs) com marcação is_federated: true.
• memory_find_path: Descoberta do caminho mais curto entre duas notas via BFS bidirecional com pesos epistêmicos.
• memory_get_impact: Análise de raio de destruição (Blast Radius) e dependentes reversos com risk scoring.
• memory_get_clusters: Detecção de comunidades e módulos temáticos via LPA ponderado e modularidade Q.
• memory_get_hubs: Identificação de God Nodes e nós líderes por grau ou PageRank ponderado.
• memory_get_insights: Métricas globais da topologia da base de conhecimento (densidade, componentes, isolados).
• memory_inspect_node: Inspeção cirúrgica de nós (in-links, out-links com sinalização cross-vault, chunks quantizados e status).
• memory_doctor: Auditoria de integridade do grafo com detecção de dead links e notas órfãs.
• memory_get_drift: Auditoria de desvio semântico e divergência entre código e documentação.
• memory_write_note: Criação de notas atômicas estruturadas com sincronização e indexação instantâneas.
• memory_append_section: Adição atômica de seções a notas existentes com auto-linking e parsing.
• memory_compile_note: Síntese de fragmentos recuperados (Compile-not-Retrieve) para economia de contexto.
• memory_pack_context: Empacotamento de orçamento de contexto de tokens (Tier L0/L1/L2) com subgrafos Mermaid.
• memory_visualize_graph: Exportação de visualizador interativo em HTML/SVG standalone com física de forças.
• memory_export_canvas: Exportação bidirecional para o padrão Obsidian JSON Canvas 1.0 (.canvas).
• memory_open_node: Abertura cirúrgica de notas locais e canônicas federadas (memory://) no editor via deep links de IDE.

📁 Estrutura do Repositório

my-memory/
├── cmd/mem/            # Ponto de entrada CLI (init, index, search, inspect, impact, drift, mcp, etc.)
├── internal/
│   ├── autowire/       # Injeção e sugestão automática de wikilinks em Markdown
│   ├── canvas/         # Conversor e exportador para formato JSON Canvas 1.0 (.canvas)
│   ├── compiler/       # Compilador semântico de contexto e síntese sob demanda
│   ├── config/         # Configuração declarativa, descoberta de vault e variáveis de ambiente
│   ├── db/             # Schemas SQLite, virtual tables sqlite-vec e queries recursivas CTE
│   ├── deeplink/       # Integração e deep linking com editores (VS Code, Cursor, Obsidian)
│   ├── drift/          # Análise de divergência semântica e staleness entre git e documentação
│   ├── embedder/       # Cliente Ollama e resolução dinâmica de modelos de embedding
│   ├── federation/     # Federação multirrepositório, RRF e resolução de URIs canônicas memory://
│   ├── graph/          # Algoritmos de grafo (LPA, modularidade Q, PageRank, Blast Radius, Inspector)
│   ├── graphview/      # Visualizador interativo HTML/SVG standalone com física de forças
│   ├── mcp/            # Servidor Model Context Protocol com 17 tools (stdio + HTTP/SSE)
│   ├── parser/         # Extração de wikilinks, tags, metadados e chunking
│   ├── repo/           # Scanner de arquivos do repositório respeitando escopo e gitignore
│   ├── staleness/      # Rastreamento de desatualização temporal de notas e links quebrados
│   ├── store/          # Camada de armazenamento unificada e suporte a PostgreSQL com pgvector
│   ├── turboquant/     # Rotações ortogonais de Householder e quantização de 4-bit
│   └── watcher/        # File watcher em segundo plano com debouncing inteligente
├── docs/               # Documentação técnica detalhada e 31 ADRs
├── COMO_USAR.md        # Manual prático passo a passo para o usuário
├── COMO_FUNCIONA.md    # Explicação detalhada da arquitetura e funcionamento interno
├── AGENTS.md           # Regras operacionais para Agentes de IA
└── README.md           # Apresentação geral do projeto

🧪 Validação e Testes

O My-Memory conta com cobertura de testes unitários e de integração em todos os 18 pacotes Go:

# Executar todos os testes do repositório
go test -count=1 ./...

# Executar testes com relatório de cobertura
go test -v -cover ./internal/turboquant/... ./internal/graph/... ./internal/parser/...

📄 Licença

Distribuído sob a licença MIT.