ogham-mcp

Configuração manual

Se você preferir configurar as coisas por conta própria em vez de usar o assistente:

# Supabase
export SUPABASE_URL=https://your-project.supabase.co
export SUPABASE_KEY=your-service-role-key
export EMBEDDING_PROVIDER=openai  # or ollama, mistral, voyage
export OPENAI_API_KEY=sk-...      # for your chosen provider

# Or Postgres (Neon, self-hosted)
export DATABASE_BACKEND=postgres
export DATABASE_URL=postgresql://user:pass@host/db
export EMBEDDING_PROVIDER=openai
export OPENAI_API_KEY=sk-...

Execute a migração do esquema (sql/schema.sql para Supabase, sql/schema_postgres.sql para Neon/auto-hospedado) e depois adicione o servidor MCP ao seu cliente.

Métodos de instalação

Claude Code

claude mcp add ogham -- uvx ogham-mcp

OpenCode -- adicione ao ~/.config/opencode/opencode.json:

{
  "mcp": {
    "ogham": {
      "type": "local",
      "command": ["uvx", "ogham-mcp"],
      "environment": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_KEY": "{env:SUPABASE_KEY}",
        "EMBEDDING_PROVIDER": "openai",
        "OPENAI_API_KEY": "{env:OPENAI_API_KEY}"
      }
    }
  }
}

Docker

docker run --rm \
  -e SUPABASE_URL=https://your-project.supabase.co \
  -e SUPABASE_KEY=your-key \
  -e EMBEDDING_PROVIDER=openai \
  -e OPENAI_API_KEY=sk-... \
  ghcr.io/ogham-mcp/ogham-mcp

A partir da fonte

git clone https://github.com/ogham-mcp/ogham-mcp.git
cd ogham-mcp
uv sync
uv run ogham --help

Transporte HTTP (multi-agente)

Por padrão, o Ogham roda em modo stdio -- cada cliente MCP inicia seu próprio processo de servidor. Para permitir que vários agentes compartilhem um servidor, execute-o via HTTP:

ogham serve --transport streamable-http --port 8742

O servidor roda como um processo de fundo persistente. Todos os clientes se conectam à mesma instância -- um pool de banco de dados, um cache de embeddings, memória compartilhada.

Configuração do cliente (qualquer cliente MCP):

{
  "mcpServers": {
    "ogham": {
      "url": "http://127.0.0.1:8742/mcp"
    }
  }
}

Verificação de saúde em http://127.0.0.1:8742/health (em cache, abaixo de 10ms). Configure via variáveis de ambiente (OGHAM_TRANSPORT=streamable-http, OGHAM_HOST, OGHAM_PORT) ou flags de CLI. http é aceito como um alias para streamable-http.

No Docker, vincule a todas as interfaces. O host padrão é 127.0.0.1, que dentro de um contêiner significa o próprio contêiner -- publicar a porta não o alcançará:

docker run -p 8742:8742 ghcr.io/ogham-mcp/ogham-mcp:latest \
  serve --transport streamable-http --host 0.0.0.0 --port 8742

SSE (legado)

O Ogham ainda aceita --transport sse e serve esse endpoint em /sse. Funciona e permanece para implantações existentes, mas novas configurações devem usar streamable-http.

A especificação MCP agora define dois transportes padrão, stdio e Streamable HTTP, e trata HTTP+SSE como obsoleto. A diferença que importa é o que acontece quando uma sessão é perdida. O Streamable HTTP atribui um Mcp-Session-Id e define o caminho de volta: o servidor responde a uma sessão morta com HTTP 404, e o cliente inicia uma nova. O SSE não define recuperação alguma, então uma sessão que perde seu estado inicializado rejeita toda solicitação posterior com -32602, e o cliente não consegue distinguir um problema de ciclo de vida de um argumento inválido. Uma conexão perdida pode deixar um agente falhando em todas as chamadas até que alguém o reinicie.

Pontos de entrada

• ogham -- a CLI. Use para ogham init, ogham health, ogham search e outros comandos que você executa. Executar ogham sem argumentos inicia o servidor MCP.
• ogham-serve -- inicia o servidor MCP diretamente. É isso que os clientes MCP devem chamar. Quando você executa uvx ogham-mcp, ele invoca ogham-serve.

85,8% de precisão de QA no harness de benchmark AMB (500 perguntas, abril de 2026) -- 429/500 perguntas respondidas corretamente usando GPT-5-mini com raciocínio, avaliado pelo Gemini 2.5 Flash Lite como avaliador estrito. R@10 de recuperação: 99,5%. AMB é o harness de avaliação padronizado construído pela equipe Vectorize (criadores do Hindsight). Agradecemos a Nicolo e à equipe Vectorize por tornar o harness aberto.

Anteriormente: 91,8% em nosso pipeline interno de benchmark LongMemEval (leitor gpt-5.4-mini, avaliador por rubrica). O número AMB é menor porque o AMB usa um avaliador mais estrito de correspondência de substring -- veja o texto completo para diferenças de metodologia.

0,554 de pontuação nugget no BEAM 100K (400 perguntas em 10 habilidades de memória, ICLR 2026), usando o prompt exato do avaliador do artigo do Apêndice G. A linha de base publicada é 0,358 (Llama-4-Maverick + LIGHT). R@10 de recuperação: 0,737. Sete de nove categorias superam o artigo. Texto completo.

Precisão de QA ponta a ponta no LongMemEval (recuperação + LLM lê e responde):

Somente recuperação (R@10 -- sem LLM no loop de busca):

Outros sistemas de recuperação que relatam números R@10 semelhantes normalmente usam reordenação por cross-encoder, verificação NLI, enriquecimento de grafo de conhecimento e pipelines de LLM-como-avaliador. O Ogham atinge 97,2% com uma consulta Postgres. Reordenação FlashRank opcional está disponível para quem quer precisão extra de classificação em auto-hospedagem.

Essas tabelas medem coisas diferentes. A precisão de QA testa se o sistema completo (recuperação + LLM) produz a resposta correta. R@10 testa se apenas a recuperação encontra as memórias certas. O Ogham é um mecanismo de recuperação -- ele encontra as memórias, seu LLM as lê.

Divisão completa: ogham-mcp.dev/features

O pipeline de recuperação do Ogham combina técnicas estabelecidas de recuperação de informação e ciência cognitiva:

• Pesquisa híbrida -- Fusão de Rank Recíproco (Cormack, Clarke & Butt, SIGIR 2009) combinando similaridade vetorial densa (pgvector) com correspondência de palavras-chave estilo BM25 (tsvector do PostgreSQL). Dois sistemas de recuperação independentes, fundidos por rank sem normalização de pontuação.

• Impulso de sobreposição de entidades -- memórias que compartilham entidades nomeadas com a consulta recebem um impulso de relevância limitado (até 1,4x), inspirado na literatura de vinculação de entidades (Kolitsas et al., CoNLL 2018). A extração de entidades cobre 18 idiomas via listas de palavras baseadas em YAML, sem LLM no caminho de escrita.

• Embeddings Matryoshka -- dimensionalidade flexível via Aprendizado de Representação Matryoshka (Kusupati et al., NeurIPS 2022). Provedores de embeddings (OpenAI, Voyage, Gemini, Ollama) produzem vetores de dimensão nativa truncados para 512d, permitindo armazenamento portátil entre provedores sem re-embedding.

• Reordenação por diversidade temporal -- penalidade suave controlada por densidade que previne agrupamento semântico em um único período de tempo, estendendo os princípios de Relevância Marginal Máxima (Carbonell & Goldstein, SIGIR 1998). Só é ativada quando os resultados top-k estão temporalmente concentrados, deixando resultados bem distribuídos intactos.

• Pontuação de importância ACT-R -- ponderação de memória inspirada em arquitetura cognitiva baseada em recência, frequência de acesso e surpresa (Anderson & Lebiere, 1998). Memórias acessadas com frequência permanecem nítidas, as raramente acessadas desaparecem, as contestadas caem no ranking sem exclusão.

• Decaimento e potencialização Hebbianos -- memórias não acessadas perdem importância ao longo do tempo (5% por período de 30 dias ocioso). Memórias acessadas 10+ vezes tornam-se "potencializadas" com uma taxa de decaimento mais lenta (1% por 30 dias), simulando potencialização de longo prazo. Baseado na regra de aprendizado de Hebb (Hebb, 1949) e em modelos computacionais de plasticidade sináptica (Bi & Poo, 2001). A importância serve como multiplicador na fórmula de relevância -- memórias em decaimento afundam nos rankings, mas permanecem recuperáveis (piso em 0,05). A importância original é preservada nos metadados para recuperação. Executado como trabalho em lote via ogham decay ou pg_cron.

• Ciclo de vida da memória (v0.11.0): FRESH / STABLE / EDITING. Cada memória agora tem um estágio explícito rastreado em uma tabela memory_lifecycle dedicada. Novas memórias chegam em fresh. O hook de início de sessão varre memórias frescas envelhecidas para stable quando elas ultrapassam um limite de importância-ou-surpresa e permaneceram tempo suficiente. A recuperação abre uma janela de 30 minutos editing nas memórias retornadas para que chamadas update_memory de acompanhamento refinem pensamentos recentes no lugar; as janelas fecham automaticamente na próxima varredura. Memórias recuperadas juntas também fortalecem suas arestas de grafo pareadas (eta=0,01 por co-recuperação, limitado a 1,0). O design se baseia em três linhas de trabalho anterior: co-ativação Hebbiana (Hebb, 1949), a curva de esquecimento híbrida exponencial-depois-lei-de-potência caracterizada por Wixted (2004) com base em Ebbinghaus (1885), e a janela de reconsolidação de memória da neurociência (Nader, Schafe & LeDoux, 2000) para o mecanismo de edição-na-recuperação. O estado do estágio vive em sua própria tabela para que as transições não toquem o índice vetorial HNSW.

• Ativação em propagação -- quando uma pesquisa atinge uma memória, a ativação se propaga ao longo das arestas de relacionamento para puxar memórias conectadas que não teriam correspondido por conta própria. Integrada em consultas de referência cruzada, ordenação e resumo. A ponderação adaptativa por densidade significa que grafos esparsos dependem mais do sinal do grafo, grafos densos dependem mais da pontuação de recuperação. Inspirado na teoria de redes semânticas de Collins & Loftus (1975).

• Detecção de contradição -- quando uma nova memória tem polaridade oposta a uma memória existente de alta similaridade, o Ogham cria automaticamente uma aresta de relacionamento contradicts. A detecção de polaridade usa marcadores de negação em 18 idiomas carregados de listas de palavras YAML. Memórias contraditas não são excluídas -- a aresta registra que a memória mais nova superou a mais antiga.

• Extração de fatos em tempo de leitura -- extração ciente da consulta no momento da recuperação preserva o armazenamento verbatim para auditabilidade, contrastando com abordagens de compressão no momento da escrita. O armazenamento verbatim garante que a verdade básica esteja sempre disponível para re-extração com diferentes perguntas posteriormente -- uma escolha de design informada por considerações de alinhamento em memória de agente persistente (Anthropic, arXiv:2510.05179). Suporta modelos locais via Ollama para soberania total de dados.

• Trilhas de auditoria somente anexação -- cada operação de armazenamento, pesquisa, exclusão e atualização é registrada em uma tabela audit_log na mesma instância Postgres. Projetado para solicitações de acesso do titular de dados do Artigo 15 do GDPR e governança de custos. Os campos estão alinhados com as Convenções Semânticas OTEL GenAI. Consulte via CLI ogham audit. Sem infraestrutura extra -- executa no mesmo banco de dados que as memórias.

ogham init                      # Interactive setup wizard
ogham health                    # Check database + embedding provider
ogham config                    # Show runtime configuration (secrets masked)
ogham store "some fact"         # Store a memory
ogham search "query"            # Search memories (hybrid: semantic + keyword)
ogham search "q" --json         # JSON output for scripting
ogham search "q" --tags "a,b"   # Filter by comma-separated tags
ogham list                      # List recent memories
ogham list --json               # JSON output
ogham delete <id>               # Delete a memory by ID
ogham use <profile>             # Switch default profile
ogham profiles                  # List profiles and counts
ogham stats                     # Profile statistics
ogham export -o backup.json     # Export memories (JSON)
ogham export --format markdown  # Export as Obsidian-compatible markdown
ogham export --format okf       # Export as Open Knowledge Format v0.1 bundle
ogham import backup.json        # Import a JSON export
ogham import <okf-bundle-dir>   # Import an OKF bundle directory (auto-detected)
ogham cleanup                   # Remove expired memories
ogham hooks install             # Auto-detect client + configure hooks
ogham hooks recall              # Read from the stone (load project context)
ogham hooks inscribe            # Carve into the stone (capture activity)
ogham hooks inscribe --dry-run  # Preview hook memory without storing
ogham serve                     # Start MCP server (stdio, default)
ogham serve --transport http    # Start HTTP server on port 8742
ogham openapi                   # Generate OpenAPI spec

Pesquisa multi-perfil -- pesquisa em vários perfis em uma única consulta (v0.8.5+):

# MCP tool
hybrid_search(query="architecture decisions", profiles=["work", "shared"])

# Python library
from ogham.service import search_memories_enriched
results = search_memories_enriched(
    query="architecture decisions",
    profile="work",
    profiles=["work", "shared", "project-alpha"],
)

Quando profiles está definido, os resultados incluem memórias de todos os perfis listados com um campo profile mostrando de qual perfil cada resultado veio.

Provedores de embeddings

EMBEDDING_DIM deve corresponder à coluna vector(N) no esquema do seu banco de dados. O esquema padrão usa vector(512). Se você usar Mistral, precisa alterar a coluna para vector(1024) antes de armazenar qualquer coisa.

Cada provedor agrupa vetores de forma diferente, então o limite de similaridade importa. Comece com o valor recomendado e ajuste com base nos seus resultados.

Pesquisa temporal -- consultas com expressões de tempo como "semana passada" ou "três meses atrás" são resolvidas automaticamente usando parsedatetime, sem necessidade de configuração. Isso cobre aproximadamente 80% das consultas temporais a custo zero. Para expressões que parsedatetime não consegue analisar ("o trimestre anterior", "perto do Dia de Ação de Graças"), defina TEMPORAL_LLM_MODEL para chamar um LLM como fallback:

# Self-hosted with Ollama (free, local)
TEMPORAL_LLM_MODEL=ollama/llama3.2

# Cloud API
TEMPORAL_LLM_MODEL=gpt-4o-mini

Qualquer string de modelo compatível com litellm funciona -- deepseek/deepseek-chat, moonshot/moonshot-v1-8k, etc. O LLM só é chamado quando parsedatetime falha e a consulta tem intenção temporal, então os custos permanecem próximos de zero. Se TEMPORAL_LLM_MODEL estiver vazio (o padrão), parsedatetime lida com tudo sozinho. Requer o pacote litellm.

Os hooks do Ogham injetam contexto de memória no início da sessão e o preservam através da compactação. Instale para seu cliente:

ogham hooks install

Dois comandos, nomeados após as pedras Ogham:

• recall -- ler da pedra. Pesquisa no Ogham por memórias relevantes ao seu projeto e as injeta como contexto. Dispara no início da sessão e após a compactação.
• inscribe -- esculpir na pedra. Captura atividade significativa de ferramentas como memórias. Ignora ruído (ls, cat, git status) e armazena apenas sinal (commits, deploys, erros, mudanças de configuração). Dispara após o uso de ferramentas e antes da compactação. Segredos são mascarados antes do armazenamento.

Desative qualquer um dos fluxos quando quiser um agente conectado ao Ogham sem permitir que ele puxe memória para o contexto ou escreva nova memória:

OGHAM_RECALL_ENABLED=false ogham serve       # no context injection / memory search
OGHAM_INSCRIBE_ENABLED=false ogham serve     # no memory capture / content writes
ogham hooks recall --no-recall               # one-off hook recall skip
ogham hooks inscribe --no-inscribe           # one-off hook capture skip
ogham search "query" --no-recall             # one-off CLI search skip
ogham store "some fact" --no-inscribe        # one-off CLI store skip

Para clientes MCP, coloque as variáveis de ambiente na configuração do servidor Ogham desse cliente:

{
  "mcpServers": {
    "ogham": {
      "command": "ogham-serve",
      "env": {
        "OGHAM_RECALL_ENABLED": "false",
        "OGHAM_INSCRIBE_ENABLED": "false"
      }
    }
  }
}

Operações administrativas como config, health, stats, audit, export, delete e cleanup permanecem disponíveis para que você possa inspecionar ou limpar a memória mesmo quando recall ou inscribe estiverem desabilitados.

Filtragem inteligente: Os hooks não capturam tudo. Comandos rotineiros (ls, pwd, git add) são ignorados. Apenas eventos de sinal (erros, deploys, commits, mudanças de configuração) são armazenados — normalmente 20 a 30 memórias por sessão, em vez de centenas.

Mascaramento de segredos: Chaves de API, tokens, senhas e JWTs são automaticamente substituídos por ***MASKED*** antes do armazenamento. O evento é capturado ("chave da API Stripe configurada"), mas o segredo real nunca toca o banco de dados.

Operações de memória

Busca

Grafo de conhecimento

Grafo de arestas tipadas (v0.16) — relacionamentos estruturais e tipados para consultas de junção de dois fatos. Detalhes completos em /docs/typed-edges/.

Importadores

Perfis

Importação / exportação

--format okf escreve um bundle compatível com Open Knowledge Format v0.1: um diretório com um arquivo markdown por memória com frontmatter YAML, um index.md na raiz do bundle declarando okf_version: "0.1", e um viewer.html autocontido (grafo Cytoscape.js, abre com file://, sem servidor ou CDN). O round-trip preserva UUID, conteúdo, tags, fonte e metadados; o embedding é regenerado na importação. Passe include_viewer=false para pular o grafo HTML. Veja o relatório de round-trip OKF para o contexto.

Manutenção

A camada wiki transforma uma tag cheia de memórias relacionadas em uma página markdown sintetizada. Execute compile_wiki em uma tag e receba um tópico resumido; o cache é invalidado automaticamente quando as memórias subjacentes mudam. Quatro ferramentas MCP cobrem o ciclo de vida:

A camada wiki precisa de um LLM. A síntese é a etapa do LLM que transforma uma lista de memórias em uma página coerente; apenas embeddings não são suficientes. Você pode executar esse LLM localmente (Ollama com llama3.2, vLLM ou qualquer servidor local compatível com OpenAI) ou na nuvem (Gemini, OpenAI, Anthropic, Mistral, Groq, OpenRouter). Local mantém tudo privado e gratuito; a nuvem geralmente escreve prosa mais polida ao custo de alguns centavos por compilação.

Defina o padrão com LLM_PROVIDER e LLM_MODEL no seu ambiente (por exemplo, LLM_PROVIDER=gemini + LLM_MODEL=gemini-2.5-flash, ou LLM_PROVIDER=ollama + LLM_MODEL=llama3.2). Substitua por chamada com compile_wiki(topic=..., provider=..., model=...). O provedor/modelo é gravado no frontmatter da página resultante, para que você possa recompilar o mesmo tópico com um LLM diferente e ver como a síntese muda.

compile_wiki faz curto-circuito quando as memórias de origem não mudaram desde a última compilação — a chamada é efetivamente gratuita se nada mudou. Passe force=True para ignorar essa verificação (útil para recompilar com um modelo diferente no mesmo conjunto de origem).

A camada wiki requer as migrações 028, 030 e 031 aplicadas ao seu banco de dados. Veja Configuração do banco de dados para detalhes.

Faça um snapshot da sua camada wiki em uma pasta de arquivos markdown compatíveis com Obsidian. Um .md por tópico com frontmatter YAML completo, além de um índice README.md. Wikilinks entre tópicos são detectados automaticamente e envolvidos em [[brackets]] para a visualização de grafo do Obsidian.

ogham export-obsidian /path/to/vault
ogham export-obsidian /path/to/vault --profile work --force

A exportação é somente leitura — ela escreve arquivos, mas nunca os lê de volta. Edições no Obsidian permanecem no Obsidian; execute a exportação novamente para atualizar o snapshot. Por design, o exportador se recusa a escrever em um diretório que já contém arquivos que ele não criou; passe --force para ignorar essa proteção.

Guia completo com referência de frontmatter, solução de problemas e capturas de tela: documentação de exportação Obsidian.

Portabilidade round-trip para suas memórias. Ogham lê e escreve Open Knowledge Format (OKF) v0.1, o formato de intercâmbio baseado em markdown que o Google Cloud publicou em junho de 2026. O mesmo bundle é portável para qualquer outra ferramenta que fale OKF — o Knowledge Catalog do Google, um leitor caseiro de um colega ou seu próprio sistema futuro.

# Export your profile as an OKF v0.1 bundle directory
ogham export --format okf

# Round-trip it back (auto-detected as an OKF bundle)
ogham import ogham-okf-<profile>-<timestamp>

O bundle é uma árvore de diretórios:

ogham-okf-<profile>-<timestamp>/
├── index.md                     # declares okf_version: "0.1"
├── viewer.html                  # self-contained Cytoscape.js graph (opens with file://)
└── memories/
    ├── <slug>-<uuid8>.md        # one markdown file per memory
    └── ...

Cada arquivo de memória tem frontmatter YAML (type, id, tags, timestamp, source, title opcional) e o corpo da memória como markdown. type: é derivado da primeira tag type:X em ordem alfabética (com fallback para Memory). O round-trip preserva UUID, conteúdo, tags, fonte e quaisquer metadados de extensão; o embedding é regenerado na importação.

O viewer.html é um arquivo autocontido de 425 KB com Cytoscape.js (MIT) embutido inline — sem servidor, sem internet, sem CDN. Abra-o em qualquer navegador via file:// para ver suas memórias como um grafo colorido por tipo, com arestas seguindo links markdown intra-bundle. Passe include_viewer=false para ignorá-lo.

Comportamento de importação:

• Memórias com a extensão id: fazem upsert por UUID (reimportações idempotentes).
• Memórias sem id: são inseridas como novas; a contagem aparece como missing_id_count no resultado.
• O importador exige um index.md na raiz do bundle com okf_version declarado, para que apontá-lo para um diretório aleatório falhe rapidamente.

Relatório voltado ao usuário: Ogham v0.15 fala Open Knowledge Format.

Do Claude Code (arquivos MD de auto-memória)

O sistema de auto-memória do Claude Code escreve notas por projeto em ~/.claude/projects/<encoded-cwd>/memory/. Cada nota é um arquivo markdown com frontmatter YAML (name, description, type, originSessionId opcional). Traga-os para o Ogham:

ogham import-claude-code ~/.claude/projects/<encoded-cwd>/memory \
    --project ogham --dedup 0.8

Cada arquivo analisável se torna uma memória Ogham marcada com source:claude-code-memory + type:<frontmatter type> + project:<inferred or explicit>. MEMORY.md (o índice) e dotfiles são ignorados. Arquivos sem frontmatter reconhecível registram um aviso e são ignorados.

A nomeação de diretórios com cwd codificado é perda de informação em nomes de repositório com hífen: openbrain-sharedmemory decodifica para sharedmemory porque cada / e - se torna o mesmo separador. Passe --project NAME para substituir a tag inferida e manter suas tags de projeto consistentes. O importador respeita inscribe_enabled() -- --no-inscribe e OGHAM_INSCRIBE_ENABLED=false pulam a importação. Re-execuções são seguras contra duplicação via o limite de cosseno --dedup (padrão 0.8). Ferramenta MCP: import_claude_code_memories(directory, project_tag=...).

Do Claude.ai (exportação de dados de conversas)

A Anthropic oferece uma exportação de dados de primeira parte em Configurações → Privacidade → Solicitar seus dados. Após ~24-48h você recebe um ZIP contendo conversations.json. Importe-o no Ogham:

ogham import-claude-ai ~/Downloads/data-<id>-batch-0000 --profile claude-ai

Aceita o próprio ZIP, o diretório descompactado ou conversations.json diretamente. Cada par de turnos (human, assistant) vira uma memória com o turno do assistente como conteúdo (o sinal que você buscará) e o prompt humano em metadata.user_prompt (recuperável para contexto). Marcação: source:claude-ai, claude-conversation:<title-slug>, project:<tag> opcional.

Um filtro inteligente conservador descarta trocas de cortesia; passe --no-smart-filter para mantê-las. Use --since 2026-01-01 para importar apenas conversas recentes, ou --mode raw para uma memória por mensagem individual em vez de por par de turnos.

Para obter um resumo destilado por LLM de uma conversa importada, chame compile_wiki(topic="claude-conversation:<slug>") via MCP. A ingestão verbatim mais a síntese sob demanda significa que você mantém os turnos brutos e obtém um resumo, sem que o importador faça chamadas LLM antecipadamente. O resumo é regenerado sempre que as memórias de origem mudam.

UUIDs da exportação vão para os metadados, então reimportar a mesma exportação depois apenas adiciona novos turnos. Ferramenta MCP: import_claude_ai_export(path, profile, mode=...).

Importações em massa pulam o enriquecimento por memória -- os importadores Claude Code, Claude.ai e JSON todos gravam via import_memories, que incorpora + deduplica + insere em lotes, mas pula a extração de entidades por memória e o auto-link (uma importação de 600 memórias executaria milhares de RPCs secundários). Memórias importadas ficam imediatamente pesquisáveis via embedding + palavra-chave. Para popular o grafo de entidades após uma importação em massa, execute ogham backfill-entities --profile <name> (veja Grafo de entidades abaixo).

De uma exportação JSON

ogham export --profile work > backup.json
ogham import backup.json --profile work-restored

Faz round-trip do esquema completo de memória (conteúdo, embeddings, tags, metadados, estado do ciclo de vida). Útil para migrar entre implantações ou semear um novo perfil a partir de outro.

O Ogham extrai tags de entidades de cada memória armazenada na ingestão (pessoas, arquivos, erros, locais, projetos -- regex puro, sem LLM). A v0.14 adicionou a conexão ao vivo para que essas tags também populam um grafo de entidades separado usado para recuperação por ativação de propagação e sugestões de conexão entre memórias.

Após aplicar a migração 036 em uma implantação existente, execute um backfill único para popular memórias históricas:

ogham backfill-entities --profile work

O backfill percorre a tabela de memórias, executa o extrator de entidades e vincula cada memória às suas entidades via link_memory_entities. ON CONFLICT DO NOTHING torna re-execuções gratuitas. Novas gravações após a v0.14 são vinculadas automaticamente; o backfill só importa para memórias criadas antes da atualização.

Uma vez que o grafo esteja populado:

• suggest_connections retorna memórias que compartilham entidades com uma memória âncora (antes sempre vazio).
• entity_graph_density retorna números reais (contagem de entidades e arestas distintas por perfil).
• O RPC spread_entity_activation_memories percorre o grafo bipartido memória/entidade para recuperação rica em contexto.

Ferramenta MCP: backfill_entities(profile=None, batch_size=200).

Pontuação e condensação -- três recursos do lado do servidor são executados automaticamente, sem necessidade de configuração:

• Detecção de novidade. Quando você armazena uma memória, o Ogham verifica o quão semelhante ela é ao que você já tem. Conteúdo redundante recebe uma pontuação de novidade menor e fica mais discreto nos resultados de busca. Você ainda pode encontrá-lo, mas ele não vai empurrar memórias mais úteis para fora.
• Pontuação de sinal de conteúdo. Memórias que mencionam decisões, erros, arquitetura ou contêm blocos de código recebem uma pontuação de sinal maior. Uma sessão de debug onde você corrigiu um bug real fica acima de uma nota casual sobre uma reunião. A pontuação é regex puro, sem LLM envolvido.
• Condensação automática. Memórias antigas que ninguém acessa encolhem gradualmente. O texto completo vira um resumo das frases-chave, depois uma descrição de uma linha com tags. O original é sempre preservado e pode ser restaurado se a memória se tornar relevante novamente. Execute compress_old_memories manualmente ou em um agendamento. Memórias de alta importância e acessadas com frequência resistem à condensação.

Enriquecimento de entidades -- toda memória é automaticamente enriquecida na ingestão com tags de entidades estruturadas, sem chamadas LLM, regex puro e correspondência de dicionário em 18 idiomas:

• Seis categorias de entidades. Eventos (casamento, show, reunião), atividades (trilha, programação, cozinhar), emoções (frustrado, feliz, aliviado), relacionamentos (irmã, chefe, colega), quantidades (3 livros, 5 milhas) e locais (Berlim, Tóquio -- via banco de dados GeoNames).
• 18 idiomas. Inglês, alemão, francês, espanhol, italiano, português, português brasileiro, holandês, polonês, russo, ucraniano, turco, árabe, hindi, japonês, coreano, chinês e irlandês. Cada idioma inclui formas flexionadas comuns (terminações de caso, tempos verbais, lenição), então "svadʹbu" corresponde a "svadʹba" em russo e "bhainis" corresponde a "bainis" em irlandês.
• Tabela de linha do tempo. Os resultados de busca incluem uma linha do tempo cronológica com "dias atrás" pré-computados e referências cruzadas de IDs de memória. Ajuda leitores LLM a responder perguntas temporais sem fazer aritmética de datas.
• Reordenação Lost in the Middle. Os resultados de busca são reordenados para que as memórias de maior relevância apareçam no início e no fim do contexto, onde os LLMs prestam mais atenção (Liu et al., 2023).

Reordenação por cross-encoder -- reordenação opcional por cross-encoder FlashRank para quem faz self-hosting e quer melhor precisão de ranqueamento. Adiciona ~300ms por busca na CPU. Após a busca híbrida do Ogham retornar candidatos, o FlashRank (ms-marco-MiniLM-L-12-v2, 21MB) reavalia cada resultado contra a consulta usando atenção mais profunda em nível de token. A pontuação final combina o ranqueamento de recuperação com o ranqueamento do cross-encoder.

Impacto no benchmark BEAM: R@10 0.69 → 0.70, MRR +8pp. Maior ganho: raciocínio temporal 0.84 → 0.98. Resultados completos.

pip install ogham-mcp[rerank]
# or: uv add ogham-mcp[rerank]

export RERANK_ENABLED=true
export RERANK_ALPHA=0.55   # 55% cross-encoder, 45% retrieval score

O modelo é baixado no primeiro uso (~21MB). Quem faz self-hosting e prefere velocidade em vez de precisão o deixa desativado (o padrão).

Embeddings locais ONNX -- execute BGE-M3 localmente com ONNX Runtime, vetores densos e esparsos em uma única passada do modelo, sem chamadas de API, sem GPU necessária. Contribuição de @ninthhousestudios. O provedor ONNX produz vetores densos de 1024 dimensões além de vetores esparsos neurais. Quando vetores esparsos estão disponíveis, o Ogham usa automaticamente a Fusão de Ranqueamento Recíproco de três sinais (denso + FTS + esparso) em vez do caminho padrão de dois sinais.

pip install ogham-mcp[onnx]

# Download the model (~2.2GB)
ogham download-model bge-m3

export EMBEDDING_PROVIDER=onnx
export EMBEDDING_DIM=1024

Seu esquema de banco de dados deve usar vector(1024) para a coluna de embeddings. Desempenho na CPU: ~0,3s por texto curto, ~10s para documentos longos (5K+ caracteres). RSS: ~4,3GB de pico. O provedor ONNX é projetado para quem faz self-hosting e quer custo zero de API. Usuários de nuvem devem usar Gemini ou Voyage para menor latência.

O Ogham funciona com Supabase ou PostgreSQL puro. Execute o arquivo de esquema que corresponde à sua configuração:

Supabase e Neon incluem pgvector de fábrica -- sem configuração extra necessária. Se você está fazendo self-hosting de Postgres, precisa de PostgreSQL 15+ com a extensão pgvector instalada. Desenvolvemos e testamos contra PostgreSQL 17. Para Postgres, defina DATABASE_BACKEND=postgres e DATABASE_URL=postgresql://... no seu ambiente.

Banco de dados de teste local pgvector -- os testes de integração Postgres são intencionalmente apenas de rascunho. Eles executam linhas reais de memória através de PostgreSQL + pgvector, mas são pulados a menos que DATABASE_URL contenha scratch ou OGHAM_TEST_ALLOW_DESTRUCTIVE=1 esteja definido. Isso impede que execuções comuns de pytest toquem um banco de dados Ogham pessoal ou de produção.

make test-postgres-db

export DATABASE_BACKEND=postgres
export DATABASE_URL=postgresql://ogham:ogham@localhost:5433/ogham_scratch

uv run pytest -m postgres_integration
# or:
make test-postgres

O harness de teste aplica o sql/schema_postgres.sql canônico a um banco de dados de rascunho vazio e reaplica as migrações de linha de base idempotentes necessárias pelos testes atuais em bancos de dados de rascunho mais antigos. Testes de integração externos Supabase + Ollama são opcionais:

OGHAM_RUN_EXTERNAL_INTEGRATION=1 uv run pytest -m integration -v
# or:
make test-external

Atualizando um banco de dados Ogham existente

Para v0.10.x → v0.11.0 (lançamento do ciclo de vida de memória), veja UPGRADING.md. A versão resumida:

./sql/upgrade.sh $DATABASE_URL     # applies 025 + 026 + 027 idempotently

Instaladores novos NÃO precisam disso -- sql/schema.sql já reflete o estado pós-v0.11.0.

Para versões mais antigas (v0.4.x até v0.10.x), o mesmo script upgrade.sh percorre cada migração em ordem -- colunas temporais, compressão halfvec, embeddings esparsos, busca RRF/BM25, depois as adições do ciclo de vida da v0.11.0. Cada uma é idempotente.

# Postgres / Neon (psql required)
./sql/upgrade.sh $DATABASE_URL

# Supabase: paste migration files into the SQL Editor in order
#   (025_memory_lifecycle.sql → 026_memory_lifecycle_split.sql → 027_audit_log_backfill.sql
#   are the v0.11.0 set)

Destaques selecionados de migração:

• 016 adiciona a coluna sparse_embedding para vetores esparsos ONNX BGE-M3.
• 017 atualiza a função de busca para Fusão de Ranqueamento Recíproco verdadeira com pontuação de palavras-chave normalizada por comprimento (Cormack et al., 2009).
• 025 / 026 adicionam a tabela de ciclo de vida de memória + triggers (veja UPGRADING.md).
• 027 faz backfill da tabela audit_log para instalações anteriores a ela.

Scripts de rollback ficam em sql/migrations/rollback/ com um prefixo DANGER_ e exigem aceitação explícita de variável de sessão antes de fazerem qualquer coisa. Veja sql/migrations/rollback/README.md.

Todas as migrações são idempotentes -- seguras para reexecutar. O script de atualização verifica sua versão do pgvector e pula halfvec se pgvector estiver abaixo de 0.7.0. Instalações novas não precisam de migrações -- os arquivos de esquema já incluem tudo.

Atualizando a CLI (ferramenta uv) -- o uv faz cache agressivamente. Um uv tool install ogham-mcp simples após um novo lançamento pode instalar a versão antiga. Use --refresh para forçar uma resolução nova do PyPI:

uv tool uninstall ogham-mcp
uv cache clean
uv tool install --refresh "ogham-mcp[gemini,postgres]"

Verifique com ogham config (mostra versão e provedor no topo). Se você ainda vir a versão antiga, apague o diretório do ambiente da ferramenta e tente novamente:

rm -rf ~/.local/share/uv/tools/ogham-mcp
uv tool install --refresh "ogham-mcp[gemini,postgres]"

Este é um comportamento de cache conhecido do uv -- o cache do resolvedor é separado do cache de pacotes e sobrevive a uv cache clean sem --refresh.

O Ogham vem com três skills de fluxo de trabalho em skills/ que conectam cadeias de ferramentas MCP comuns. Instale-os no Claude Code, Cursor ou qualquer cliente que suporte skills.

As skills chamam ferramentas MCP existentes -- elas não as substituem. O servidor MCP deve estar conectado para que as skills funcionem.

npx skills add ogham-mcp/ogham-mcp                        # all three
npx skills add ogham-mcp/ogham-mcp --skill ogham-recall   # one
cp -r skills/ogham-research skills/ogham-recall skills/ogham-maintain ~/.claude/skills/   # manual