Mnemex

CortexGraph: Memória Temporal para IA

Um servidor Model Context Protocol (MCP) que fornece dinâmicas de memória semelhantes às humanas para assistentes de IA. As memórias desaparecem naturalmente com o tempo, a menos que sejam reforçadas pelo uso, imitando a curva de esquecimento de Ebbinghaus.

[!NOTE] Sobre o Nome e a Versão

Este projeto foi originalmente desenvolvido como mnemex (publicado no PyPI até a v0.6.0). Em novembro de 2025, foi transferido para Prefrontal Systems e renomeado para CortexGraph para refletir melhor seu papel em uma arquitetura cognitiva mais ampla para sistemas de IA.

A numeração de versão começa em 0.1.0 para o pacote cortexgraph para sinalizar um novo começo sob o novo nome, ao mesmo tempo em que reconhece a base de código madura e bem testada (791 testes, cobertura de 98%+) herdada do mnemex. O pacote mnemex permanece congelado na v0.6.0 no PyPI.

Essa abordagem de versionamento:

• Sinaliza "novo pacote" para usuários do PyPI que descobrem o cortexgraph
• Dá espaço para evoluir a marca, a API e a integração organizacional antes da 1.0
• Mantém a continuidade: usuários podem migrar de pip install mnemex → pip install cortexgraph
• Reflete que, embora o código seja maduro, a identidade do cortexgraph está apenas começando

[!IMPORTANT] 🔬 ARTEFATO DE PESQUISA - NÃO PARA PRODUÇÃO

Este software é uma Prova de Conceito (PoC) e implementação de referência para fins de pesquisa. Ele existe para validar estruturas teóricas em arquitetura cognitiva e segurança de IA (especificamente o Protocolo STOPPER e o CortexGraph).

NÃO é um produto comercial. Não é mantido para uso geral em produção, pode conter mudanças que quebram compatibilidade e não oferece garantias de estabilidade ou suporte. Use-o para estudar os conceitos, mas construa suas próprias implementações de produção.

📖 Novo neste projeto? Comece com o Guia ELI5 para uma explicação simples do que isso faz e como usar.

O que é o CortexGraph?

O CortexGraph dá aos assistentes de IA, como o Claude, um sistema de memória semelhante ao humano.

O Problema

Quando você conversa com o Claude, ele esquece tudo entre as conversas. Você diz "Prefiro TypeScript" ou "Sou alérgico a amendoim", e três dias depois, você tem que repetir. Isso é frustrante e perde tempo.

O que o CortexGraph Faz

O CortexGraph faz os assistentes de IA lembrarem das coisas naturalmente, assim como a memória humana:

• 🧠 Lembra o que importa - Suas preferências, decisões e fatos importantes
• ⏰ Esquece naturalmente - Informações antigas e não utilizadas desaparecem com o tempo (como a curva de esquecimento de Ebbinghaus)
• 💪 Fica mais forte com o uso - Quanto mais você referencia algo, mais tempo é lembrado
• 📦 Salva coisas importantes permanentemente - Memórias usadas com frequência são promovidas para armazenamento de longo prazo

Como Funciona (Versão Simples)

1. Você fala naturalmente - "Prefiro modo escuro em todos os meus aplicativos"
2. A memória é salva automaticamente - Nenhum comando especial é necessário
3. O tempo passa - A memória desaparece gradualmente se não for usada
4. Você referencia novamente - "Coloque este aplicativo em modo escuro"
5. A memória fica mais forte - Agora dura ainda mais
6. Memórias importantes são promovidas - Usado 5+ vezes? Salvo permanentemente no seu cofre do Obsidian

Sem flashcards. Sem revisão explícita. Apenas conversa natural.

Por que é Diferente

A maioria dos sistemas de memória é burra:

• ❌ "Excluir após 7 dias" (não se importa se você usou 100 vezes)
• ❌ "Manter os últimos 100 itens" (joga fora coisas importantes só porque são antigas)

O CortexGraph é inteligente:

• ✅ Combina recência (quando?), frequência (com que frequência?) e importância (quão crítico?)
• ✅ Memórias desaparecem naturalmente como a memória humana
• ✅ Memórias usadas com frequência duram mais
• ✅ Você pode marcar coisas críticas para "nunca esquecer"

Visão Geral Técnica

Este repositório contém pesquisa, design e uma implementação completa de um sistema de memória de curto prazo que combina:

• Novo algoritmo de decaimento temporal baseado em ciência cognitiva
• Aprendizado por reforço através de padrões de uso
• Arquitetura de duas camadas (STM + LTM) para memória de trabalho e permanente
• Padrões de prompt inteligentes para integração natural com LLM
• Armazenamento amigável ao Git com JSONL legível por humanos
• Grafo de conhecimento com entidades e relações

Organização dos Módulos

O CortexGraph segue uma arquitetura modular:

• cortexgraph.core: Algoritmos fundamentais (decaimento, similaridade, agrupamento, consolidação, validação de busca)
• cortexgraph.agents: Pipeline de consolidação multiagente e utilitários de armazenamento
• cortexgraph.storage: Backends de armazenamento JSONL e SQLite com operações em lote
• cortexgraph.tools: Implementações de ferramentas MCP

Por que o CortexGraph?

🔒 Privacidade e Transparência

Todos os dados armazenados localmente na sua máquina - sem serviços em nuvem, sem rastreamento, sem compartilhamento de dados.

• Memória de curto prazo:

  • JSONL (padrão): Arquivos legíveis por humanos e amigáveis ao Git (~/.config/cortexgraph/jsonl/)
  • SQLite: Armazenamento robusto em banco de dados para conjuntos de dados maiores (~/.config/cortexgraph/cortexgraph.db)

• Memória de longo prazo: Arquivos Markdown otimizados para Obsidian

  • Frontmatter YAML com metadados
  • Wikilinks para conexões
  • Armazenamento permanente que você controla

• Exportação: Utilitário integrado para exportar memórias para Markdown para portabilidade.

Você é dono dos seus dados. Você pode lê-los, editá-los, excluí-los ou controlar versões - tudo sem ferramentas especiais.

Algoritmo Principal

A função de pontuação de decaimento temporal:

$$ \Large \text{score}(t) = (n_{\text{use}})^\beta \cdot e^{-\lambda \cdot \Delta t} \cdot s $$

Onde:

• $\large n_{\text{use}}$ - Contagem de uso (número de acessos)
• $\large \beta$ (beta) - Ponderação sublinear da contagem de uso (padrão: 0.6)
• $\large \lambda = \frac{\ln(2)}{t_{1/2}}$ (lambda) - Constante de decaimento; definida via meia-vida (padrão: 3 dias)
• $\large \Delta t$ - Tempo desde o último acesso (segundos)
• $\large s$ - Parâmetro de força $\in [0, 2]$ (multiplicador de importância)

Limiares:

• $\large \tau_{\text{forget}}$ (padrão 0.05) — se a pontuação < este valor, esqueça
• $\large \tau_{\text{promote}}$ (padrão 0.65) — se a pontuação ≥ este valor, promova (ou se $\large n_{\text{use}}\ge5$ em 14 dias)

Modelos de Decaimento:

• Lei de Potência (padrão): cauda mais pesada; retenção mais semelhante à humana
• Exponencial: cauda mais leve; esquece mais cedo
• Dois Componentes: esquecimento inicial rápido + cauda mais pesada

Consulte a referência detalhada de parâmetros, seleção de modelos e exemplos práticos em docs/scoring_algorithm.md.

Folha de Dicas de Ajuste

• Equilibrado (padrão)
  • Meia-vida: 3 dias (λ ≈ 2.67e-6)
  • β = 0.6, τ_forget = 0.05, τ_promote = 0.65, use_count≥5 em 14d
  • Força: 1.0 (aumente para 1.3–2.0 para crítico)
• Contexto de alta velocidade (notas efêmeras, troca rápida)
  • Meia-vida: 12–24 horas (λ ≈ 1.60e-5 a 8.02e-6)
  • β = 0.8–0.9, τ_forget = 0.10–0.15, τ_promote = 0.70–0.75
• Retenção longa (pesquisa/arquivamento)
  • Meia-vida: 7–14 dias (λ ≈ 1.15e-6 a 5.73e-7)
  • β = 0.3–0.5, τ_forget = 0.02–0.05, τ_promote = 0.50–0.60
• Assistentes com muitas preferências/decisões
  • Meia-vida: 3–7 dias; β = 0.6–0.8
  • Força padrão: 1.3–1.5 para preferências; 1.8–2.0 para decisões
• Controle agressivo de espaço
  • Aumente τ_forget para 0.08–0.12 e/ou encurte a meia-vida; agende GC semanal
• Modelo de ambiente
  • CORTEXGRAPH_DECAY_LAMBDA=2.673e-6, CORTEXGRAPH_DECAY_BETA=0.6
  • CORTEXGRAPH_FORGET_THRESHOLD=0.05, CORTEXGRAPH_PROMOTE_THRESHOLD=0.65
  • CORTEXGRAPH_PROMOTE_USE_COUNT=5, CORTEXGRAPH_PROMOTE_TIME_WINDOW=14

Limiares de decisão:

• Esquecer: $\text{score} < 0.05$ → excluir memória
• Promover: $\text{score} \geq 0.65$ OU $n_{\text{use}} \geq 5$ em 14 dias → mover para LTM

Principais Inovações

1. Decaimento Temporal com Reforço

Ao contrário do cache tradicional (TTL, LRU), o Mnemex pontua memórias continuamente combinando recência (decaimento exponencial), frequência (contagem de uso sublinear) e importância (força ajustável). Veja Algoritmo Principal para a fórmula matemática. Isso cria dinâmicas de memória que imitam de perto a cognição humana.

2. Sistema de Prompt Inteligente + Ativação por Linguagem Natural (v0.6.0+)

Padrões para fazer assistentes de IA usarem memória naturalmente, agora aprimorados com extração automática de entidades e pontuação de importância:

Auto-Enriquecimento (NOVO na v0.6.0)

Quando você salva memórias, o CortexGraph automaticamente:

• Extrai entidades (pessoas, tecnologias, organizações) usando spaCy NER
• Calcula importância/força com base em marcadores de conteúdo
• Detecta intenção de salvar/recuperar a partir de frases em linguagem natural

# Before v0.6.0 - manual entity specification
save_memory(content="Use JWT for auth", entities=["JWT", "auth"])

# v0.6.0+ - automatic extraction
save_memory(content="Use JWT for auth")
# Entities auto-extracted: ["jwt", "auth"]
# Strength auto-calculated based on content

Auto-Salvamento

User: "Remember: I prefer TypeScript over JavaScript"
→ Detected save phrase: "Remember"
→ Automatically saved with:
   - Entities: [typescript, javascript]
   - Strength: 1.5 (importance marker detected)
   - Tags: [preferences, programming]

Auto-Recuperação

User: "What did I say about TypeScript?"
→ Detected recall phrase: "what did I say about"
→ Automatically searches for TypeScript memories
→ Retrieves preferences and conventions

Auto-Reforço

User: "Yes, still using TypeScript"
→ Memory strength increased, decay slowed

Ferramentas de Suporte à Decisão (v0.6.0+)

Duas novas ferramentas ajudam o Claude a decidir quando salvar/recuperar:

• analyze_message - Detecta conteúdo digno de memória, sugere entidades e força
• analyze_for_recall - Detecta intenção de recuperação, sugere consultas de busca

Nenhum comando explícito de memória necessário - apenas conversa natural.

3. Repetição Espaçada Natural

Inspirado em como conceitos se reforçam naturalmente em diferentes contextos (o "efeito Maslow" - lembrar melhor da hierarquia de Maslow quando aparece em aulas de história, economia e sociologia).

Sem flashcards. Sem sessões explícitas de revisão. Apenas conversa natural.

Como funciona:

1. Cálculo de Prioridade de Revisão - Memórias na "zona de perigo" (pontuação de decaimento 0.15-0.35) recebem prioridade máxima
2. Detecção entre Domínios - Detecta quando memórias são usadas em contextos diferentes (similaridade Jaccard de tags <30%)
3. Reforço Automático - Memórias se fortalecem naturalmente quando usadas, especialmente entre domínios
4. Busca Combinada - Candidatos a revisão aparecem em 30% dos resultados de busca (configurável)

Padrão de uso:

User: "Can you help with authentication in my API?"
→ System searches, retrieves JWT preference memory
→ System uses memory to answer question
→ System calls observe_memory_usage with context tags [api, auth, backend]
→ Cross-domain usage detected (original tags: [security, jwt, preferences])
→ Memory automatically reinforced, strength boosted
→ Next search naturally surfaces memories needing review

Configuração:

CORTEXGRAPH_REVIEW_BLEND_RATIO=0.3           # 30% review candidates in search
CORTEXGRAPH_REVIEW_DANGER_ZONE_MIN=0.15      # Lower bound of danger zone
CORTEXGRAPH_REVIEW_DANGER_ZONE_MAX=0.35      # Upper bound of danger zone
CORTEXGRAPH_AUTO_REINFORCE=true              # Auto-reinforce on observe

Veja docs/prompts/ para modelos de prompt de sistema para LLM que permitem uso natural de memória.

4. Arquitetura de Duas Camadas

graph TD
    STM["<b>Short-Term Memory</b><br/>- JSONL storage<br/>- Temporal decay<br/>- Hours to weeks retention"]
    LTM["<b>LTM (Long-Term Memory)</b><br/>- Markdown files Obsidian<br/>- Permanent storage<br/>- Git version control"]
    
    STM -->|Automatic promotion| LTM
    
    style STM fill:#e1f5ff,stroke:#01579b,stroke-width:2px
    style LTM fill:#f3e5f5,stroke:#4a148c,stroke-width:2px

5. Pipeline de Consolidação Multiagente

Manutenção automatizada de memória através de cinco agentes especializados:

graph LR
    decay["<b>DecayAnalyzer</b><br/>Find at-risk<br/>memories"]
    cluster["<b>ClusterDetector</b><br/>Find similar<br/>groups"]
    merge["<b>SemanticMerge</b><br/>Combine<br/>similar groups"]
    promote["<b>LTMPromoter</b><br/>Promote<br/>to LTM"]
    relations["<b>RelationshipDiscovery</b><br/>Discover cross-<br/>domain links"]
    
    decay --> cluster
    cluster --> merge
    merge --> promote
    promote --> relations
    relations -.->|feedback| decay
    
    style decay fill:#ffebee,stroke:#b71c1c,stroke-width:2px
    style cluster fill:#fff3e0,stroke:#e65100,stroke-width:2px
    style merge fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    style promote fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
    style relations fill:#e1f5fe,stroke:#01579b,stroke-width:2px

Os Cinco Agentes:

Agente	Propósito
DecayAnalyzer	Encontrar memórias em risco de serem esquecidas (zona de perigo: 0.15-0.35)
ClusterDetector	Agrupar memórias semelhantes usando similaridade de embeddings
SemanticMerge	Combinar inteligentemente memórias agrupadas, preservando informações únicas
LTMPromoter	Mover memórias de alto valor para armazenamento permanente no Obsidian
RelationshipDiscovery	Encontrar conexões entre domínios via entidades compartilhadas

Principais Recursos:

• Modo de simulação (dry-run): Visualizar alterações sem modificar dados
• Limitação de taxa: Operações configuráveis por minuto (padrão: 60)
• Trilha de auditoria: Cada decisão rastreada via rastreamento de problemas beads
• Intervenção humana: Revisar e aprovar decisões antes da execução

Uso:

from cortexgraph.agents import Scheduler

# Preview what would change (dry run)
scheduler = Scheduler(dry_run=True)
preview = scheduler.run_pipeline()

# Run full pipeline
scheduler = Scheduler(dry_run=False)
results = scheduler.run_pipeline()

# Run single agent
decay_results = scheduler.run_agent("decay")

CLI:

# Dry run (preview)
cortexgraph-consolidate --dry-run

# Run specific agent
cortexgraph-consolidate --agent decay --dry-run

# Scheduled execution (with interval)
cortexgraph-consolidate --scheduled --interval-hours 1

Veja docs/agents.md para documentação completa incluindo configuração, integração com beads e solução de problemas.

Início Rápido

Instalação

Recomendado: Instalação via UV Tool (do PyPI)

# Install from PyPI (recommended - fast, isolated, includes all 7 CLI commands)
uv tool install cortexgraph

Isso instala cortexgraph e todos os 7 comandos CLI em um ambiente isolado.

Métodos Alternativos de Instalação

# Using pipx (similar isolation to uv)
pipx install cortexgraph

# Using pip (traditional, installs in current environment)
pip install cortexgraph

# From GitHub (latest development version)
uv tool install git+https://github.com/simplemindedbot/cortexgraph.git

Para Desenvolvimento (Instalação Editável)

# Clone and install in editable mode
git clone https://github.com/simplemindedbot/cortexgraph.git
cd cortexgraph
uv pip install -e ".[dev]"

Configuração

IMPORTANTE: A localização da configuração depende do método de instalação:

Método 1: Arquivo .env (Funciona para todos os métodos de instalação)

Crie ~/.config/cortexgraph/.env:

# Create config directory
mkdir -p ~/.config/cortexgraph

# Option A: Copy from cloned repo
cp .env.example ~/.config/cortexgraph/.env

# Option B: Download directly
curl -o ~/.config/cortexgraph/.env https://raw.githubusercontent.com/simplemindedbot/cortexgraph/main/.env.example

Edite ~/.config/cortexgraph/.env com suas configurações:

# Storage
CORTEXGRAPH_STORAGE_PATH=~/.config/cortexgraph/jsonl

# Decay model (power_law | exponential | two_component)
CORTEXGRAPH_DECAY_MODEL=power_law

# Power-law parameters (default model)
CORTEXGRAPH_PL_ALPHA=1.1
CORTEXGRAPH_PL_HALFLIFE_DAYS=3.0

# Exponential (if selected)
# CORTEXGRAPH_DECAY_LAMBDA=2.673e-6  # 3-day half-life

# Two-component (if selected)
# CORTEXGRAPH_TC_LAMBDA_FAST=1.603e-5  # ~12h
# CORTEXGRAPH_TC_LAMBDA_SLOW=1.147e-6  # ~7d
# CORTEXGRAPH_TC_WEIGHT_FAST=0.7

# Common parameters
CORTEXGRAPH_DECAY_LAMBDA=2.673e-6
CORTEXGRAPH_DECAY_BETA=0.6

# Thresholds
CORTEXGRAPH_FORGET_THRESHOLD=0.05
CORTEXGRAPH_PROMOTE_THRESHOLD=0.65

# Long-term memory (optional)
LTM_VAULT_PATH=~/Documents/Obsidian/Vault

Onde o cortexgraph procura arquivos .env:

1. Primário: ~/.config/cortexgraph/.env ← Use isso para uv tool install / uvx
2. Alternativo: ./.env (diretório atual) ← Só funciona para instalações editáveis

Configuração MCP

Recomendado: Use caminho absoluto (funciona em qualquer lugar)

Adicione a ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cortexgraph": {
      "command": "/Users/yourusername/.local/bin/cortexgraph"
    }
  }
}

Encontre seu caminho real:

which cortexgraph
# Example output: /Users/yourusername/.local/bin/cortexgraph

Use esse caminho na sua configuração. Substitua yourusername pelo seu nome de usuário real.

Por que caminho absoluto? Aplicativos GUI como o Claude Desktop não herdam a configuração de PATH do seu shell (.zshrc, .bashrc). Usar o caminho completo garante que funcione sempre.

Para desenvolvimento (instalação editável):

{
  "mcpServers": {
    "cortexgraph": {
      "command": "uv",
      "args": ["--directory", "/path/to/cortexgraph", "run", "cortexgraph"],
      "env": {"PYTHONPATH": "/path/to/cortexgraph/src"}
    }
  }
}

A configuração pode ser carregada de ./.env no diretório do projeto OU ~/.config/cortexgraph/.env.

Solução de problemas: Comando não encontrado

Se o Claude Desktop mostrar erros de spawn cortexgraph ENOENT, o comando cortexgraph não está no PATH do Claude Desktop.

macOS/Linux: aplicativos GUI não herdam o PATH do shell

Aplicativos GUI no macOS e Linux não veem a configuração de PATH do seu shell (.zshrc, .bashrc, etc.). O Claude Desktop pesquisa apenas:

• /usr/local/bin
• /opt/homebrew/bin (macOS)
• /usr/bin
• /bin
• /usr/sbin
• /sbin

Se uv tool install colocou cortexgraph em ~/.local/bin/ ou outro local personalizado, o Claude Desktop não consegue encontrá-lo.

Solução: Use caminho absoluto

# Find where cortexgraph is installed
which cortexgraph
# Example output: /Users/username/.local/bin/cortexgraph

Atualize sua configuração do Claude com o caminho absoluto:

{
  "mcpServers": {
    "cortexgraph": {
      "command": "/Users/username/.local/bin/cortexgraph"
    }
  }
}

Substitua /Users/username/.local/bin/cortexgraph pelo seu caminho real de which cortexgraph.

Manutenção

Use a CLI de manutenção para inspecionar e compactar o armazenamento JSONL:

# Show storage stats (active counts, file sizes, compaction hints)
cortexgraph-maintenance stats

# Compact JSONL (rewrite without tombstones/duplicates)
cortexgraph-maintenance compact

Migrando para instalação via UV Tool

Se você está usando uma instalação editável (uv pip install -e .), pode mudar para a instalação mais simples via UV tool:

# 1. Uninstall editable version
uv pip uninstall cortexgraph

# 2. Install as UV tool
uv tool install git+https://github.com/simplemindedbot/cortexgraph.git

# 3. Update Claude Desktop config to just:
#    {"command": "cortexgraph"}
#    Remove the --directory, run, and PYTHONPATH settings

Seus dados estão seguros! Isso apenas muda como o comando é instalado. Suas memórias em ~/.config/cortexgraph/ não são alteradas.

Comandos CLI

O servidor inclui 7 ferramentas de linha de comando:

cortexgraph                  # Run MCP server
cortexgraph-migrate          # Migrate from old STM setup
cortexgraph-index-ltm        # Index Obsidian vault
cortexgraph-backup           # Git backup operations
cortexgraph-vault            # Vault markdown operations
cortexgraph-search           # Unified STM+LTM search
cortexgraph-maintenance      # JSONL storage stats and compaction

Visualização

Visualização interativa de grafos usando PyVis:

# Install visualization dependencies
pip install "cortexgraph[visualization]"
# or with uv
uv pip install "cortexgraph[visualization]"

# Or install dependencies manually
pip install pyvis networkx

# Generate interactive HTML visualization
python scripts/visualize_graph.py

# Custom output location
python scripts/visualize_graph.py --output ~/Desktop/memory_graph.html

# Custom data paths
python scripts/visualize_graph.py --memories ~/data/memories.jsonl --relations ~/data/relations.jsonl

Recursos:

• Grafo de rede interativo com pan/zoom
• Cores dos nós por status (ativo=azul, promovido=verde, arquivado=cinza)
• Tamanho do nó baseado na contagem de uso
• Cores das arestas por tipo de relação
• Tooltips ao passar o mouse mostrando conteúdo completo, tags e entidades
• Controles de física para ajuste do layout

A visualização lê diretamente dos seus arquivos JSONL e cria um arquivo HTML autônomo que você pode abrir em qualquer navegador.

Ferramentas MCP

13 ferramentas para assistentes de IA gerenciarem memórias:

Ferramenta	Propósito
save_memory	Salvar nova memória com tags, entidades (auto-enriquecimento na v0.6.0+)
search_memory	Buscar com filtros e pontuação (inclui candidatos a revisão)
search_unified	Busca unificada entre MCP + MLP
touch_memory	Reforçar memória (aumentar força)
observe_memory_usage	Registrar uso de memória para repetição espaçada natural
analyze_message	✨ NOVO v0.6.0 - Detectar conteúdo digno de memória, sugerir entidades/força
analyze_for_recall	✨ NOVO v0.6.0 - Detectar intenção de recall, sugerir consultas de busca
gc	Coleta de lixo de memórias com baixa pontuação
promote_memory	Mover para armazenamento de longo prazo
cluster_memories	Encontrar memórias semelhantes
consolidate_memories	Mesclar memórias semelhantes (algorítmico)
read_graph	Obter grafo de conhecimento completo
open_memories	Recuperar memórias específicas
create_relation	Vincular memórias explicitamente

Exemplo: Busca Unificada

Busque em MCP e MLP com a CLI:

cortexgraph-search "typescript preferences" --tags preferences --limit 5 --verbose

Exemplo: Reforçar (Tocar) Memória

Aumente a recência/contagem de uso de uma memória para desacelerar o decaimento:

{
  "memory_id": "mem-123",
  "boost_strength": true
}

Resposta de exemplo:

{
  "success": true,
  "memory_id": "mem-123",
  "old_score": 0.41,
  "new_score": 0.78,
  "use_count": 5,
  "strength": 1.1
}

Exemplo: Promover Memória

Sugira e promova memórias de alto valor para o cofre do Obsidian.

Detecção automática (dry run):

{
  "auto_detect": true,
  "dry_run": true
}

Promover uma memória específica:

{
  "memory_id": "mem-123",
  "dry_run": false,
  "target": "obsidian"
}

Como ferramenta MCP (corpo da requisição):

{
  "query": "typescript preferences",
  "tags": ["preferences"],
  "limit": 5,
  "verbose": true
}

Exemplo: Consolidar Memórias Semelhantes

Encontre e mescle memórias duplicadas ou muito semelhantes para reduzir a desordem:

Detecção automática de candidatos (pré-visualização):

{
  "auto_detect": true,
  "mode": "preview",
  "cohesion_threshold": 0.75
}

Aplicar consolidação aos clusters detectados:

{
  "auto_detect": true,
  "mode": "apply",
  "cohesion_threshold": 0.80
}

A ferramenta irá:

• Mesclar conteúdo de forma inteligente (preservando informações únicas)
• Combinar tags e entidades (união)
• Calcular força com base na coesão do cluster
• Preservar os timestamps mais antigos de created_at e mais recentes de last_used
• Criar relações de rastreamento mostrando o histórico de consolidação

Detalhes Matemáticos

Curvas de Decaimento

Para uma memória com $n_{\text{use}}=1$, $s=1.0$, e $\lambda = 2.673 \times 10^{-6}$ (meia-vida de 3 dias):

Tempo	Pontuação	Status
0 horas	1.000	Recente
12 horas	0.917	Ativa
1 dia	0.841	Ativa
3 dias	0.500	Meia-vida
7 dias	0.210	Decaindo
14 dias	0.044	Quase esquecida
30 dias	0.001	Esquecida

Impacto da Contagem de Uso

Com $\beta = 0.6$ (ponderação sub-linear):

Contagem de Uso	Fator de Reforço
1	1.0×
5	2.6×
10	4.0×
50	11.4×

Acesso frequente estende significativamente a retenção.

Documentação

• Referência de Ferramentas MCP - Documentação abrangente para todas as 18 ferramentas MCP
• Referência Rápida da API - Assinaturas mínimas de ferramentas e exemplos de uso
• Algoritmo de Pontuação - Modelo matemático completo com fórmulas LaTeX
• Prompting Inteligente - Padrões para integração natural com LLM
• Arquitetura - Design do sistema e implementação
• Sistema Multi-Agente - Agentes de consolidação e arquitetura de pipeline
• Integração com Bear - Guia para usar o app Bear como armazenamento LTM
• Recursos de Grafo - Uso do grafo de conhecimento

Casos de Uso

Assistente Pessoal (Equilibrado)

• Meia-vida de 3 dias
• Lembrar preferências e decisões
• Promover automaticamente informações referenciadas com frequência

Ambiente de Desenvolvimento (Agressivo)

• Meia-vida de 1 dia
• Troca rápida de contexto
• Esquecimento agressivo de contexto antigo

Pesquisa / Arquivamento (Conservador)

• Meia-vida de 14 dias
• Retenção longa
• Preservação abrangente do conhecimento

Licença

Licença AGPL-3.0 - Veja LICENSE para detalhes.

Este projeto usa a Licença Pública Geral Affero GNU v3.0, que exige que modificações neste software sejam disponibilizadas como código-fonte quando usado para fornecer um serviço de rede.

Trabalhos Relacionados

• Model Context Protocol - Especificação MCP
• Curva do Esquecimento de Ebbinghaus - Fundação da ciência cognitiva
• Basic Memory - Inspiração principal para a camada de integração. O CortexGraph estende esse conceito adicionando a curva do esquecimento de Ebbinghaus, algoritmos de decaimento temporal, memória de curto prazo em armazenamento JSONL e repetição espaçada natural.
• Pesquisa adicional inspirada por: mem0, Neo4j Graph Memory

Citação

Se você usar este trabalho em pesquisa, por favor cite:

@software{cortexgraph_2025,
  title = {Mnemex: Temporal Memory for AI},
  author = {simplemindedbot},
  year = {2025},
  url = {https://github.com/simplemindedbot/cortexgraph},
  version = {0.5.3}
}

Contribuindo

Contribuições são bem-vindas! Veja CONTRIBUTING.md para instruções detalhadas.

🚨 Ajuda Necessária: Testadores Windows e Linux!

Eu desenvolvo no macOS e preciso de ajuda para testar no Windows e Linux. Se você tem acesso a essas plataformas, por favor:

• Tente as instruções de instalação
• Execute a suíte de testes
• Reporte o que funciona e o que não funciona

Veja a seção Ajuda Necessária no CONTRIBUTING.md para detalhes.

Contribuições Gerais

Para todos os contribuidores, veja CONTRIBUTING.md para:

• Configuração específica por plataforma (Windows, Linux, macOS)
• Fluxo de trabalho de desenvolvimento
• Diretrizes de teste
• Requisitos de estilo de código
• Processo de pull request

Início rápido:

1. Leia CONTRIBUTING.md para configuração específica por plataforma
2. Entenda a documentação de Arquitetura
3. Revise o Algoritmo de Pontuação
4. Siga os padrões de código existentes
5. Adicione testes para novos recursos
6. Atualize a documentação

Status

Versão: 1.0.0 Status: Implementação de pesquisa - funcional, mas em evolução

Fase 1 (Concluída) ✅

• 14 ferramentas MCP
• Algoritmo de decaimento temporal
• Grafo de conhecimento

Fase 2 (Concluída) ✅

• Armazenamento JSONL
• Índice LTM
• Integração com Git
• Documentação de prompting inteligente
• CLI de manutenção
• Consolidação de memória (mesclagem algorítmica)

Fase 3 (Concluída) ✅

• Pipeline de Consolidação Multi-Agente
  • DecayAnalyzer, ClusterDetector, SemanticMerge, LTMPromoter, RelationshipDiscovery
  • Agendador para orquestração
  • Integração de rastreamento de issues Beads
  • Suporte a dry-run e limite de taxa
• Ativação por linguagem natural (v0.6.0+)
• Auto-enriquecimento para extração de entidades

Trabalho Futuro

• Parâmetros de decaimento adaptativos
• Benchmarks de desempenho
• Consolidação assistida por LLM (melhoria opcional)

---

Construído com Claude Code 🤖