MCP Knowledge Graph

Fornece memória persistente para modelos de IA usando um grafo de conhecimento local.

Documentação

MCP Knowledge Graph

Memória persistente para modelos de IA por meio de um grafo de conhecimento local.

Armazene e recupere informações entre conversas usando entidades, relações e observações. Funciona com Claude Code/Desktop e qualquer plataforma de IA compatível com MCP.

Por que os prefixos ".aim" e "aim_"?

AIM significa AI Memory (Memória de IA) - o conceito central deste sistema. Os três elementos AIM fornecem organização e segurança claras:

Diretórios .aim: Mantêm os arquivos de memória de IA organizados e facilmente identificáveis
Prefixos de ferramentas aim_: Agrupam funções de memória relacionadas em configurações com múltiplas ferramentas
Marcadores de segurança _aim: Cada arquivo de memória começa com {"type":"_aim","source":"mcp-knowledge-graph"} para evitar sobrescritas acidentais de arquivos JSONL não relacionados

Essa nomenclatura AIM consistente torna óbvio quais diretórios, ferramentas e arquivos pertencem ao sistema de memória de IA.

CRÍTICO: Entendendo o diretório `.aim` vs o marcador de arquivo `_aim`

Duas coisas diferentes com nomes semelhantes:

.aim = Nome do diretório local do projeto (DEVE ser nomeado exatamente como .aim para que a detecção de projeto funcione)
_aim = Marcador de segurança de arquivo (aparece dentro dos arquivos JSONL: {"type":"_aim","source":"mcp-knowledge-graph"})

Para armazenamento local do projeto:

O diretório DEVE ser nomeado .aim na raiz do seu projeto
Exemplo: my-project/.aim/memory.jsonl
O sistema procura especificamente por esse nome exato

Para armazenamento global (--memory-path):

Pode ser QUALQUER diretório que você quiser
Exemplos: ~/yourusername/.aim/, ~/memories/, ~/Dropbox/ai-memory/, ~/Documents/ai-data/
Flexibilidade total - escolha o local que funcionar para você

Lógica de Armazenamento

Prioridade de Localização de Arquivos:

Projeto com .aim - Usa .aim/memory.jsonl (local do projeto)
Sem projeto/sem .aim - Usa o diretório global configurado
Contextos - Adiciona sufixo: memory-work.jsonl, memory-personal.jsonl

Sistema de Segurança:

Todo arquivo de memória começa com {"type":"_aim","source":"mcp-knowledge-graph"}
O sistema se recusa a gravar em arquivos sem esse marcador
Evita a sobrescrita acidental de arquivos JSONL não relacionados

Conceito de Banco de Dados Mestre

O banco de dados mestre é seu armazenamento de memória principal - usado por padrão quando nenhum banco de dados específico é solicitado. Ele é sempre nomeado default nas listagens e armazenado como memory.jsonl.

Comportamento Padrão: Todas as operações de memória usam o banco de dados mestre, a menos que você especifique um diferente
Sempre Disponível: Existe tanto nos locais locais do projeto quanto nos globais
Armazenamento Primário: Seu principal grafo de conhecimento que persiste em todas as conversas
Bancos de Dados Nomeados: Bancos de dados adicionais opcionais (work, personal, health) para organizar tópicos específicos

Principais Recursos

Banco de Dados Mestre: Armazenamento de memória principal usado por padrão para todas as operações
Múltiplos Bancos de Dados: Bancos de dados nomeados opcionais para organizar memórias por tópico
Detecção de Projeto: Memória automática local do projeto usando diretórios .aim
Substituição de Localização: Força operações a usar armazenamento do projeto ou global
Operações Seguras: Proteção integrada contra sobrescrita de arquivos não relacionados
Descoberta de Bancos de Dados: Lista todos os bancos de dados disponíveis em ambos os locais

Início Rápido

Memória Global (Recomendado)

Adicione ao seu claude_desktop_config.json ou .claude.json. Duas abordagens comuns:

Opção 1: Diretório .aim padrão (simples)

{
  "mcpServers": {
    "Aim-Memory-Bank": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-knowledge-graph",
        "--memory-path",
        "/Users/yourusername/.aim"
      ]
    }
  }
}

Opção 2: Sincronização Dropbox/nuvem (portátil)

Para acessar memórias em várias máquinas, use uma pasta sincronizada. É assim que o autor deste servidor MCP mantém suas próprias memórias:

{
  "mcpServers": {
    "Aim-Memory-Bank": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-knowledge-graph",
        "--memory-path",
        "/Users/yourusername/Dropbox/ai-memory"
      ]
    }
  }
}

Isso cria arquivos de memória no diretório especificado:

memory.jsonl - Banco de Dados Mestre (padrão para todas as operações)
memory-work.jsonl - Banco de dados de trabalho
memory-personal.jsonl - Banco de dados pessoal
etc.

Memória Local do Projeto

Em qualquer projeto, crie um diretório .aim:

mkdir .aim

Agora as ferramentas de memória usam automaticamente .aim/memory.jsonl (banco de dados mestre local do projeto) em vez do armazenamento global quando executadas a partir deste projeto.

Como a IA Usa Bancos de Dados

Uma vez configurado, os modelos de IA usam o banco de dados mestre por padrão ou podem especificar bancos de dados nomeados com um parâmetro context. Novos bancos de dados são criados automaticamente - nenhuma configuração necessária:

// Master Database (default - no context needed)
aim_memory_store({
  entities: [{
    name: "John_Doe",
    entityType: "person",
    observations: ["Met at conference"]
  }]
})

// Work database
aim_memory_store({
  context: "work",
  entities: [{
    name: "Q4_Project",
    entityType: "project",
    observations: ["Due December 2024"]
  }]
})

// Personal database
aim_memory_store({
  context: "personal",
  entities: [{
    name: "Mom",
    entityType: "person",
    observations: ["Birthday March 15th"]
  }]
})

// Master database in specific location
aim_memory_store({
  location: "global",
  entities: [{
    name: "Important_Info",
    entityType: "reference",
    observations: ["Stored in global master database"]
  }]
})

Organização de Arquivos

Configuração Global:

/Users/yourusername/.aim/
├── memory.jsonl           # Master Database (default)
├── memory-work.jsonl      # Work database
├── memory-personal.jsonl  # Personal database
└── memory-health.jsonl    # Health database

Configuração do Projeto:

my-project/
├── .aim/
│   ├── memory.jsonl       # Project Master Database (default)
│   └── memory-work.jsonl  # Project Work database
└── src/

Ferramentas Disponíveis

aim_memory_store - Armazena novas memórias (pessoas, projetos, conceitos)
aim_memory_add_facts - Adiciona fatos a memórias existentes
aim_memory_link - Vincula duas memórias
aim_memory_search - Busca memórias por palavra-chave
aim_memory_get - Recupera memórias específicas pelo nome exato
aim_memory_read_all - Lê todas as memórias em um banco de dados
aim_memory_list_stores - Lista bancos de dados disponíveis
aim_memory_forget - Esquece memórias
aim_memory_remove_facts - Remove fatos específicos de uma memória
aim_memory_unlink - Remove vínculos entre memórias

Parâmetros

context (opcional) - Especifica banco de dados nomeado (work, personal, etc.). Padrão: banco de dados mestre
location (opcional) - Força o local de armazenamento project ou global. Padrão: detecção automática

Descoberta de Bancos de Dados

Use aim_memory_list_stores para ver todos os bancos de dados disponíveis:

{
  "project_databases": [
    "default",      // Master Database (project-local)
    "project-work"  // Named database
  ],
  "global_databases": [
    "default",      // Master Database (global)
    "work",
    "personal",
    "health"
  ],
  "current_location": "project (.aim directory detected)"
}

Pontos-chave:

"default" = Banco de Dados Mestre em ambos os locais
Local atual mostra se você está usando armazenamento do projeto ou global
O banco de dados mestre existe em todos os lugares - é seu armazenamento de memória principal
Bancos de dados nomeados são adições opcionais para tópicos específicos

Exemplos de Configuração

Importante: Sempre especifique --memory-path para controlar onde seus arquivos de memória são armazenados.

Aprovar automaticamente operações de leitura (recomendado):

{
  "mcpServers": {
    "Aim-Memory-Bank": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-knowledge-graph",
        "--memory-path",
        "/Users/yourusername/.aim"
      ],
      "autoapprove": [
        "aim_memory_search",
        "aim_memory_get",
        "aim_memory_read_all",
        "aim_memory_list_stores"
      ]
    }
  }
}

Solução de Problemas

Erro "File does not contain required _aim safety marker":

O arquivo pode não pertencer a este sistema
Arquivos JSONL manuais precisam de {"type":"_aim","source":"mcp-knowledge-graph"} como primeira linha
Se você criou o arquivo manualmente, adicione o marcador _aim ou exclua e deixe o sistema recriá-lo

Memórias indo para locais inesperados:

Verifique se você está em um diretório de projeto com a pasta .aim (usa armazenamento local do projeto)
Caso contrário, usa o diretório global --memory-path configurado
Use aim_memory_list_stores para ver todos os bancos de dados disponíveis e o local atual
Use ls .aim/ ou ls /Users/yourusername/.aim/ para ver seus arquivos de memória

Muitos bancos de dados semelhantes:

Os modelos de IA tentam usar nomes consistentes, mas podem criar variações
Exclua manualmente arquivos de banco de dados indesejados, se necessário
Incentive a IA a usar nomes de banco de dados simples e consistentes
Lembre-se: O banco de dados mestre está sempre disponível como padrão - bancos de dados nomeados são opcionais

Requisitos

Node.js 22+
Plataforma de IA compatível com MCP

Licença

MIT

MCP Knowledge Graph

Documentação