grkmemory 1.21.0

GRKMemory (Graph Retrieve Knowledge Memory) - A semantic graph-based memory system for AI agents developed by MonkAI team

🧠 GRKMemory - Graph Retrieve Knowledge Memory

GRKMemory = Graph Retrieve Knowledge Memory

GRKMemory é um sistema de memória semântica baseado em grafos para agentes de IA, desenvolvido pelo time MonkAI. Recuperação inteligente de conhecimento com grande economia de tokens (~95% em nossos benchmarks internos — veja Performance).

🚀 Começando

1️⃣ Instalação

pip install grkmemory        # sempre em um venv (ou via pipx)

Requer Python 3.10–3.13 (distribuímos apenas wheels compilados, sem sdist).

Instalando no Python do sistema (Debian/Ubuntu, devcontainers de IDE)? Prefira um venv ou pipx install --python python3.12 grkmemory — o site-packages do sistema não entra no caminho e nada conflita. Se precisar instalar direto no sistema e o pip falhar com "Cannot uninstall PyJWT... no RECORD" (o extra [mcp] puxa pyjwt>=2.10.1 via SDK MCP, e o PyJWT do apt não pode ser removido pelo pip), use: pip install --ignore-installed PyJWT "grkmemory[mcp]".

2️⃣ Token de acesso (opcional — só para o gate de autenticação)

O uso direto da biblioteca (GRKMemory, MemoryRepository, servidor MCP, plugin Claude Code) não exige token. O token MonkAI só é necessário se você quiser a camada opcional de controle de acesso (GRKAuth/AuthenticatedGRK) — útil quando vários times/serviços compartilham o mesmo store:

📧 Contato: [e-mail]
🌐 Site: www.monkai.com.br

3️⃣ Configurar Token

# Configurar como variável de ambiente
export GRKMEMORY_API_KEY="grk_seu_token_aqui"

# OpenAI (padrão)
export OPENAI_API_KEY="sua_openai_key"

# OU Azure OpenAI
export USE_AZURE_OPENAI="true"
export AZURE_OPENAI_API_KEY="sua_azure_key"
export AZURE_OPENAI_ENDPOINT="https://seu-recurso.openai.azure.com"
export AZURE_OPENAI_DEPLOYMENT="gpt-4o"
export AZURE_OPENAI_EMBEDDING_DEPLOYMENT="text-embedding-3-small"

4️⃣ Autenticar e Usar

from grkmemory import GRKMemory, GRKAuth, AuthenticatedGRK

# Autenticar com token MonkAI
auth = GRKAuth.from_env()  # Usa GRKMEMORY_API_KEY
print("✅ Autenticado!")

# Inicializar GRKMemory protegido
grk = GRKMemory()
secure = AuthenticatedGRK(grk, auth.get_current_token())

# Usar!
secure.save_conversation([
    {"role": "user", "content": "Olá!"},
    {"role": "assistant", "content": "Oi! Como posso ajudar?"}
])

results = secure.search("Olá")

🎯 Quick Start (Completo)

from grkmemory import GRKMemory, GRKAuth, AuthenticatedGRK
import os

# 1. Autenticar
api_key = os.getenv("GRKMEMORY_API_KEY")
auth = GRKAuth()
auth.authenticate(api_key)

# 2. Criar GRKMemory autenticado
grk = GRKMemory()
secure = AuthenticatedGRK(grk, api_key)

# 3. Salvar conversa
secure.save_conversation([
    {"role": "user", "content": "Vamos falar sobre Python"},
    {"role": "assistant", "content": "Claro! O que você quer saber?"}
])

# 4. Buscar memórias relevantes
results = secure.search("O que discutimos sobre Python?")

# 5. Chat com contexto de memória automático
response = secure.chat("Me conte sobre nossas discussões anteriores")

🔐 Autenticação

Token MonkAI

A autenticação é uma camada de proteção opcional: ela só entra em cena quando você envolve a lib com GRKAuth/AuthenticatedGRK para dar a cada consumidor um token com permissões próprias (vários times/serviços num mesmo store). O uso direto — GRKMemory, MemoryRepository, servidor MCP, plugin Claude Code — funciona sem nenhum token (ver "Modo Offline (Sem Token)" abaixo). O que o GRKMemory/MemoryConfig exigem é uma chave OpenAI/Azure (para o chat agent e embeddings de API) — e mesmo essa é dispensável com MemoryRepository(enable_embeddings=False) ou com o provider local (grkmemory[local-embeddings]).

Permissão	Descrição
read	Buscar e consultar memórias
write	Salvar novas memórias
admin	Gerenciamento completo

Métodos de Autenticação

from grkmemory import GRKAuth

# Método 1: Via variável de ambiente (recomendado)
auth = GRKAuth.from_env()  # Usa GRKMEMORY_API_KEY

# Método 2: Diretamente
auth = GRKAuth()
auth.authenticate("grk_seu_token")

# Verificar permissões
print(f"Pode ler: {auth.check_permission('read')}")
print(f"Pode escrever: {auth.check_permission('write')}")

⚠️ Importante: Tokens são fornecidos exclusivamente pelo time MonkAI.

⚙️ Configuração

from grkmemory import GRKMemory, MemoryConfig

config = MemoryConfig(
    model="gpt-4o",
    memory_file="minhas_memorias.json",
    enable_embeddings=True,
    background_memory_method="graph",  # 'graph', 'embedding', 'tags', 'entities', 'hybrid'
    background_memory_limit=5,
    background_memory_threshold=0.3,
    storage_format="json",   # 'json' (padrão) ou 'toon'
    output_format="json"     # 'json', 'toon', 'text' ou 'raw'
)

grk = GRKMemory(config=config)

🗄️ Backends de Armazenamento (file / postgres)

O armazenamento e a busca vetorial vivem atrás de uma interface StorageBackend plugável. O default (file) mantém o comportamento histórico — um único arquivo plano (JSON/TOON, opcionalmente criptografado) com índice FAISS em memória. Ele é seguro apenas em processo único: dois processos compartilhando o mesmo MEMORY_FILE competem (último a escrever vence). Para um servidor com memória que precisa escalar horizontalmente, externalize o storage para remover esse acoplamento a instância-única + volume persistente.

Backend	Concorrência	Quando usar
file (default)	processo único	dev local, single-instance, sem nova dependência
postgres	entre processos (transacional)	produção horizontal/stateless

Seleção via ambiente (ou MemoryConfig):

# Default — nada muda
GRKMEMORY_STORAGE_BACKEND=file

# pgvector (requer o extra grkmemory[postgres])
GRKMEMORY_STORAGE_BACKEND=postgres
GRKMEMORY_POSTGRES_DSN=postgresql://user:pass@host:5432/db
GRKMEMORY_EMBEDDING_DIM=1536   # dimensão do embedding (default 1536)

pip install "grkmemory[postgres]"   # instala psycopg + pgvector

A biblioteca base nunca importa psycopg — o PostgresVectorBackend é resolvido sob demanda, então quem usa o backend file não ganha dependência nova. O backend externo cria a tabela + índice ANN HNSW (cosseno) na primeira inicialização. O grafo semântico continua sendo reconstruído em memória a partir dos registros (v1 não persiste arestas no banco).

Também é possível injetar um backend diretamente:

from grkmemory.memory.repository import MemoryRepository
from grkmemory.memory.backends import PostgresVectorBackend

backend = PostgresVectorBackend(dsn="postgresql://...", embedding_dim=1536)
repo = MemoryRepository(backend=backend)

☁️ Azure OpenAI

GRKMemory suporta Azure OpenAI nativamente. Configure via variáveis de ambiente ou código:

Via Variáveis de Ambiente

export USE_AZURE_OPENAI="true"
export AZURE_OPENAI_API_KEY="sua-api-key"
export AZURE_OPENAI_ENDPOINT="https://seu-recurso.openai.azure.com"
export AZURE_OPENAI_DEPLOYMENT="gpt-4o"
export AZURE_OPENAI_EMBEDDING_DEPLOYMENT="text-embedding-3-small"
export AZURE_OPENAI_API_VERSION="2024-02-01"  # opcional

Via Código

from grkmemory import GRKMemory, MemoryConfig

# Configuração Azure OpenAI
config = MemoryConfig(
    use_azure=True,
    api_key="sua-azure-api-key",
    azure_endpoint="https://seu-recurso.openai.azure.com",
    azure_deployment="gpt-4o",
    azure_embedding_deployment="text-embedding-3-small",
    azure_api_version="2024-02-01"
)

grk = GRKMemory(config=config)

Tabela de Configurações Azure

Variável	Config	Descrição
USE_AZURE_OPENAI	use_azure	Ativar Azure (true/false)
AZURE_OPENAI_API_KEY	api_key	Chave da API Azure
AZURE_OPENAI_ENDPOINT	azure_endpoint	URL do recurso Azure
AZURE_OPENAI_DEPLOYMENT	azure_deployment	Nome do deployment (chat)
AZURE_OPENAI_EMBEDDING_DEPLOYMENT	azure_embedding_deployment	Nome do deployment (embeddings)
AZURE_OPENAI_API_VERSION	azure_api_version	Versão da API (default: 2024-02-01)

📦 Formatos de Armazenamento (JSON vs TOON)

GRKMemory suporta dois formatos de serialização:

Formato	Vantagem	Uso Recomendado
JSON	Parsing 27x mais rápido	Armazenamento (padrão)
TOON	25% menos tokens	Contexto para LLM

Instalando TOON (opcional)

pip install toon_format

Estratégia Híbrida (Recomendada)

from grkmemory import MemoryRepository

# JSON para armazenamento (rápido) + TOON para LLM (economia de tokens)
repo = MemoryRepository(
    memory_file="memorias.json",
    storage_format="json",      # Parsing rápido
    output_format="toon"        # 25% menos tokens para LLM
)

# Buscar e formatar para LLM
results = repo.search("Python")
context = repo.format_for_llm(results)  # Retorna em TOON (~25% menos tokens)

Comparando Formatos

# Estimar economia de tokens
estimates = repo.get_token_estimate(results)
print(estimates)
# {'json': 689, 'toon': 512, 'savings_toon_vs_json': '25.7%'}

✂️ output_format="raw" — Modo enxuto de tokens

Quando o consumidor downstream só precisa do conteúdo da resposta (a mensagem do assistant) e não dos metadados de cada memória (summary, tags, entities, sentiment, etc.), use output_format="raw". Devolve apenas o content do primeiro turno de assistant de cada conversa recuperada, separado por \n\n---\n\n.

repo = MemoryRepository(
    memory_file="memorias.json",
    output_format="raw",
)

results = repo.search("capital da França")
context = repo.format_for_llm(results)
# "A capital da França é Paris."
# (sem JSON wrapper, sem metadados, sem labels)

Benchmark (issue #13)

47k chars de snapshot, 30 queries, gpt-4.1-mini + judge gpt-4.1 (rubrica 0–3):

Formato	input tokens	judge	recall vs json
json (default)	1.705	1.47	igual
toon	1.475	1.47	igual
text	252	1.00	cai (perde conversation)
raw	640	1.47	igual

→ ~2.7× mais barato que json com recall idêntico em consultas factuais. Use quando o LLM downstream só precisa do que o assistente respondeu antes; use json/toon quando o LLM precisa raciocinar sobre tags/sentiment/confidence.

🔍 preserve_identifiers — Recall em corpus pequeno/identifier-dense

O KnowledgeAgent resume cada conversa antes de embeddar, o que é ótimo para chat narrativo, mas descarta tokens identificadores (semver v1.6.0, issue refs #42, env vars OPENAI_API_KEY, key=value floor_value=30) — justamente o que consultas factuais matcham. Em corpus pequeno/identifier-dense (<~95k tokens), cosine ingênuo sobre chunks crus chega a vencer o GRKMemory em 0.3–1.1 pontos de judge nessas consultas. Acima de ~95k tokens o GRKMemory volta a ganhar (a discriminação semântica supera o "imposto" da perda de surface).

A solução é um dual-index opt-in:

from grkmemory import MemoryConfig, GRKMemory

cfg = MemoryConfig(
    preserve_identifiers=True,  # default False — opt-in, sem custo se off
    # identifier_regex=...      # opcional; default cobre semver/#issue/SCREAMING_SNAKE/key_=val
    background_memory_method="hybrid",  # max-pool sobre os 2 embeddings
)

grk = GRKMemory(config=cfg)
grk.save_conversation([
    {"role": "user", "content": "qual a última versão?"},
    {"role": "assistant", "content": "Liberamos v1.6.0 no PyPI ontem."},
])

# Consulta factual com surface token — o embedding do summary largou "v1.6.0",
# mas o embedding_identifier preservou. O hybrid recupera.
results = grk.search("v1.6.0")

O que muda no schema

Quando ligado, cada memória ganha 2 campos:

• identifiers: List[str] — tokens extraídos do conversation[assistant].content
• embedding_identifier: List[float] — vetor sobre {summary} {identifiers}

search(method="hybrid") calcula max(cos(query, embedding), cos(query, embedding_identifier)) por memória. Custo extra: 1 chamada de embedding adicional por save() (zero se o regex não casa nada nessa memória). Default off — backwards compatible.

Padrões cobertos pelo regex default

Padrão	Exemplo
semver	v1.6.0, 0.47.0-rc1
issue ref	#42, #300
SCREAMING_SNAKE	OPENAI_API_KEY, RUN_LLM_E2E
lower_snake=value	floor_value=30, top_k=5

Customizável via identifier_regex ou env IDENTIFIER_REGEX.

Convertendo entre Formatos

# Exportar para TOON
repo.export("backup.toon", format="toon")

# Converter armazenamento para TOON
repo.convert_storage_format("toon")

👥 Multi-tenant (user_id / session_id / tenant_id)

O que é privado e o que é compartilhado? (modelo de escopo)

A dúvida mais comum de quem consome o GRKMemory: "a memória é compartilhada entre todos os projetos? como compartilho só dentro de um projeto?". A regra é uma só:

Memória salva com um tenant_id só aparece em buscas com o mesmo tenant_id. Sem tenant_id (None), a memória vai para o namespace global — visível para qualquer busca que também não passe tenant.

Ou seja: nada é "compartilhado com todos os projetos" por acidente — o escopo é sempre o tenant em uso. O que muda entre os modos de consumo é quem define o tenant:

Como você usa	Escopo default	Para compartilhar só num projeto/time
Lib Python direta	Global (tenant_id=None)	Todos os consumidores do projeto usam o mesmo tenant: MemoryConfig(tenant_id="meu-projeto") ou env GRKMEMORY_TENANT_ID
Plugin Claude Code	Por projeto (tenant = slug do diretório do repo) — nada vaza entre projetos	Já é assim por default; mesmo diretório ⇒ mesma memória
MCP remoto — token estático / GRKAuth	GRKMEMORY_TENANT_ID do servidor, ou o tenant_id que o chamador passar	Combinar um tenant_id por projeto e passá-lo nas tools
MCP remoto — token introspectado (ex.: hub multi-tenant)	Privado: default_tenant do token	Passar o tenant_id de um espaço compartilhado listado em allowed_tenants do token (qualquer outro é rejeitado, fail-closed)

Os detalhes de cada modo estão nas seções seguintes e em Emissor de tokens (introspecção).

Como funciona o filtro

É possível isolar memórias por usuário, sessão e/ou tenant usando os parâmetros opcionais user_id, session_id e tenant_id em save_conversation, search, chat, get_stats e get_top_memories. O armazenamento continua em um único arquivo/store; o filtro é aplicado na busca.

# Salvar conversa para um usuário/sessão
grk.save_conversation(
    [{"role": "user", "content": "Olá!"}, {"role": "assistant", "content": "Oi!"}],
    user_id="user_123",
    session_id="sess_abc"
)

# Buscar apenas memórias desse usuário
results = grk.search("Olá", user_id="user_123")

# Ou apenas dessa sessão
results = grk.search("Olá", session_id="sess_abc")

# Chat e save também aceitam user_id/session_id
response = grk.chat("O que discutimos?", user_id="user_123")

Sem user_id/session_id, o comportamento é o mesmo de antes (todas as memórias são consideradas).

Isolamento por tenant (stores compartilhados)

Use tenant_id para garantir que dois tenants com o mesmo user_id em um store compartilhado nunca vejam as memórias um do outro. A chave efetiva de isolamento é tenant × user × session.

from grkmemory import GRKMemory, MemoryConfig

# Uma instância GRKMemory por tenant (recomendado para stores compartilhados)
grk = GRKMemory(MemoryConfig(tenant_id="tenant_x"))
grk.save_conversation(msgs, user_id="guest")   # armazenado sob tenant_x
grk.search("pedidos", user_id="guest")          # escopo restrito a tenant_x

# Ou sobrescrever por chamada
grk.search("pedidos", user_id="guest", tenant_id="other_tenant")

tenant_id=None (padrão) preserva o namespace global existente — nenhum deploy atual precisa mudar. A variável GRKMEMORY_TENANT_ID define o padrão no config via env.

⏳ Fatos temporais (bi-temporalidade)

Fatos mudam com o tempo ("threshold aprovado = 0.7" → semanas depois "= 0.5"). Cada memória pode carregar uma janela de validade [valid_from, valid_until) além do created_at, e uma memória nova pode superseder a antiga sem apagá-la:

# Janela de validade explícita no save (opcional)
repo.save({"summary": "threshold aprovado = 0.7", "tags": ["threshold"],
           "valid_from": "2026-01-10T00:00:00"})
repo.save({"summary": "threshold aprovado = 0.5", "tags": ["threshold"],
           "valid_from": "2026-03-15T00:00:00"})

# A decisão nova supersede a antiga (anotação, nunca delete)
grk.supersede(old_id, new_id)

# Recall padrão = "válido agora": só o fato vigente aparece
grk.search("threshold")

# Time-travel: o que era verdade em fevereiro?
grk.search("threshold", as_of="2026-02-01T00:00:00")

Regras: valid_until é exclusivo; sem campos de validade a memória é sempre válida (100% retrocompatível); em consultas as_of explícitas o created_at faz papel de valid_from quando este falta. A memória superada continua acessível via as_of e get_memory_detail — o campo superseded_by aponta para quem a substituiu. Detecção automática de supersessão (LLM/heurística) está fora de escopo por ora (ver issue #50).

🧹 Operações administrativas (listar e apagar)

Para diagnóstico e limpeza — os endpoints /admin típicos de um consumidor — use a API pública em vez de alcançar _repository.memories ou _save_to_file():

# Listagem: mais recente primeiro, com escopo, limite e sem os vetores
recentes = grk.list_memories(limit=20)
do_tenant = grk.list_memories(tenant_id="acme", user_id="u1", limit=100)

# Remoção: dry-run por default — a primeira chamada só reporta o que sairia
previa = grk.delete_memories(predicate=lambda m: "stub" in m.get("tags", []))
# {'matched': 7, 'deleted': 0, 'dry_run': True, 'ids': [...]}

# Confirmar exige dry_run=False explícito
grk.delete_memories(predicate=lambda m: "stub" in m.get("tags", []), dry_run=False)
# {'matched': 7, 'deleted': 7, 'dry_run': False, 'ids': [...]}

# Ids conhecidos são só um predicate
grk.delete_memories(predicate=lambda m: m["id"] in ids, dry_run=False)

• Persistência, invalidação de cache e rebuild do grafo acontecem dentro da lib. Nenhum consumidor precisa (nem deve) chamar _save_to_file() / _invalidate_query_cache() — era exatamente essa sequência que quebrava a cada minor.
• Escopo é guard rail, não conveniência: tenant_id/user_id/session_id limitam o alcance mesmo com um predicate que casa tudo. Sem escopo e sem predicate, delete_memories levanta ValueError em vez de apagar o store inteiro — para isso existe clear().
• list_memories devolve cópias sem embedding/embedding_identifier (passe include_embeddings=True se precisar deles).
• Em GRKMemory, tenant_id cai para config.tenant_id quando omitido, como em get_stats.

🔌 Servidor MCP (grkmemory[mcp])

Exponha a memória como tools para qualquer cliente MCP (Claude Code, claude.ai, Agent SDK):

pip install grkmemory[mcp]

# Claude Code
claude mcp add grkmemory -- grkmemory-mcp

Tools expostas: memory_save (ingestão sem LLM — summary/tags/entities/key_points precomputados), memory_search (métodos graph/embedding/tags/entities/hybrid + as_of para time-travel), memory_supersede, memory_get, memory_stats_tool.

Configuração 100% via env vars padrão da lib (MEMORY_FILE, GRKMEMORY_STORAGE_BACKEND file/postgres, GRKMEMORY_TENANT_ID, BACKGROUND_MEMORY_LIMIT, ...). Embeddings ligam automaticamente quando há credencial OpenAI/Azure no ambiente (OPENAI_API_KEY/AZURE_OPENAI_API_KEY/AZURE_FOUNDRY_KEY) ou ENABLE_EMBEDDINGS=true; sem credencial o recall usa graph/tags/entities e o servidor funciona 100% offline com o file backend. Embeddings nunca aparecem nos payloads das tools.

Instalação por IDE (VS Code / JetBrains) e Claude Desktop

As extensões de IDE do Claude Code leem a mesma configuração MCP do CLI: .mcp.json na raiz do projeto (escopo projeto, versionável) ou ~/.claude.json (escopo user). Não precisa de terminal para ativar — gere o arquivo pronto com:

grkmemory-mcp init             # cria/mescla ./.mcp.json (escopo projeto)
grkmemory-mcp init --desktop   # idem para o Claude Desktop (type: stdio, paths absolutos)
grkmemory-mcp init --memory-file /outro/caminho/memoria.json

O comando aponta o bloco grkmemory para o binário em execução (path absoluto), define MEMORY_FILE (default ~/.grkmemory/memoria.json, diretório criado na hora) e preserva outros servidores já configurados no arquivo. Na primeira abertura a extensão pede aprovação do servidor; use /mcp no chat para ver o status da conexão.

Bloco gerado (referência, caso prefira escrever à mão):

{
  "mcpServers": {
    "grkmemory": {
      "command": "/caminho/venv/bin/grkmemory-mcp",
      "args": [],
      "env": { "MEMORY_FILE": "/Users/voce/.grkmemory/memoria.json" }
    }
  }
}

Alternativa zero-install com uv: "command": "uvx", "args": ["--from", "grkmemory[mcp]", "grkmemory-mcp"].

Recall vetorial sem chave de API (grkmemory[local-embeddings]): com GRKMEMORY_EMBEDDING_PROVIDER=local, os métodos embedding/hybrid rodam com modelo on-device (fastembed/ONNX, default sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2, 384 dims, multilíngue — ~120MB baixados no primeiro uso; troque via GRKMEMORY_LOCAL_EMBEDDING_MODEL, precisa ser modelo suportado pelo fastembed). O servidor MCP liga embeddings automaticamente nesse modo — memória semântica 100% offline e keyless. Com pgvector, aponte GRKMEMORY_EMBEDDING_DIM para a dimensão do modelo.

Embeddings via Google/Gemini (grkmemory[google-embeddings]): com GRKMEMORY_EMBEDDING_PROVIDER=google (alias gemini) e GOOGLE_API_KEY ou GEMINI_API_KEY, os métodos embedding/hybrid rodam pela API Gemini — caminho de menor atrito para quem já tem credencial Google e não quer contratar OpenAI/Azure nem baixar modelo local. Modelo default gemini-embedding-001 (troque via GRKMEMORY_GOOGLE_EMBEDDING_MODEL); GRKMEMORY_EMBEDDING_TIMEOUT e GRKMEMORY_EMBEDDING_MAX_RETRIES valem igual aos demais providers.

Dimensão importa. Os modelos Google têm largura nativa própria (3072 no gemini-embedding-001), enquanto a coluna pgvector é criada com GRKMEMORY_EMBEDDING_DIM (default 1536). O provider repassa essa variável como output_dimensionality, então setá-la é o que faz o vetor caber na coluna — e um vetor de largura divergente levanta erro em vez de ser gravado. Ao trocar de provider num store já populado, os vetores antigos continuam na métrica antiga: rode grkmemory-mcp backfill-embeddings depois de alinhar a dimensão.

Quando a chave falha ou os créditos acabam

Leitura falha alto. search(method='embedding'/'hybrid') levanta EmbeddingProviderError com a causa classificada, em vez de devolver lista vazia (que se confunde com "tenant sem memórias"). O method='graph' continua funcionando sem chave nenhuma, então é o fallback durante o incidente.

Escrita, por padrão, não falha: o registro é gravado com vetor vazio e só sobra um log de erro. O problema é que ele continua invisível para busca vetorial depois que a chave é consertada, até alguém rodar grkmemory-mcp backfill-embeddings. Para recusar a escrita em vez de guardar um registro sem vetor:

export GRKMEMORY_STRICT_EMBEDDINGS=true      # ou MemoryRepository(strict_embeddings=True)

A causa vem classificada, porque a ação é diferente em cada caso (e a OpenAI reporta crédito esgotado como 429, a mesma classe de um rate limit comum):

from grkmemory import EmbeddingProviderError

try:
    grk.search("assunto", method="embedding")
except EmbeddingProviderError as e:
    e.kind  # 'quota_exhausted' | 'invalid_credential' | 'rate_limited' | 'connection' | 'unknown'

kind	O que fazer
quota_exhausted	recarregar créditos ou subir o limite (é cobrança, não chave errada)
invalid_credential	conferir ou rotacionar a chave
rate_limited	reduzir o ritmo e repetir
connection	checar rede/endpoint

Não existe troca automática de provider (OpenAI cair e Gemini assumir): é um provider por processo, definido por env. Antes de desistir, ambos respeitam GRKMEMORY_EMBEDDING_TIMEOUT (15s) e GRKMEMORY_EMBEDDING_MAX_RETRIES (1).

Recall não é automático só com o MCP: instalar o servidor torna as tools disponíveis — o Claude decide chamá-las pelo contexto. Para memória verdadeiramente automática, use o plugin abaixo.

Plugin Claude Code (memória automática)

O plugin adiciona hooks que fazem o ciclo completo sem nenhuma instrução:

• UserPromptSubmit → busca memórias relevantes para o prompt e injeta como contexto do turno (recall automático, escopado por projeto);
• Stop/SessionEnd → destila a sessão (tarefa + desfecho + conceitos) e salva/atualiza uma memória por sessão, com segredos redactados antes de persistir;
• comando /memoria → buscar, salvar, supersedir e inspecionar pela conversa;
• registra o MCP server automaticamente (dispensa .mcp.json).

pip install "grkmemory[mcp]"        # o plugin usa o grkmemory-mcp do PATH (ou uvx)
/plugin marketplace add BeMonkAI/GRKMemory
/plugin install grkmemory@grkmemory

Os hooks nunca quebram a sessão (falhas vão para stderr e saem 0) e funcionam offline (recall graph/tags). Store default ~/.grkmemory/memoria.json; escopo por projeto via tenant_id derivado do diretório.

Sessões headless (claude -p em automação): as tools MCP entram deferred; use ENABLE_TOOL_SEARCH=false claude -p ... para carregá-las upfront.

Sessões cloud / claude.ai (MCP remoto via HTTP)

Sessões em containers efêmeros (Claude Code web, conectores claude.ai) não conseguem usar o transporte stdio local — o binário e o arquivo de memória evaporam com o container. Para esse caso, rode o servidor em um host seu e conecte por URL:

# no host (Railway, VM, etc.)
export GRKMEMORY_MCP_TOKENS="grk_um_token_por_consumidor"   # auth é OBRIGATÓRIA no modo HTTP
export GRKMEMORY_STORAGE_BACKEND=postgres                    # recomendado (multi-instância)
export GRKMEMORY_POSTGRES_DSN=postgres://...
grkmemory-mcp serve --http --host 0.0.0.0 --port 8080

Requisição sem token válido recebe 401 — um servidor exposto sem auth configurada nem sobe (fail-fast). Alternativa ao token estático: um arquivo de tokens GRKAuth (GRKMEMORY_TOKENS_FILE) com ciclo de vida completo via grkmemory-token (permissões, revogação).

Emissor de tokens (introspecção)

Terceira fonte de validação — em vez de token estático ou arquivo GRKAuth locais, o servidor delega a validação a um emissor remoto (qualquer serviço que implemente o contrato abaixo). Útil quando quem emite/revoga tokens é um serviço externo (ex.: um hub multi-tenant) em vez do próprio operador do grkmemory-mcp.

export GRKMEMORY_TOKEN_INTROSPECTION_URL="https://seu-emissor/introspect"
export GRKMEMORY_TOKEN_INTROSPECTION_SECRET="segredo-compartilhado"
grkmemory-mcp serve --http --host 0.0.0.0 --port 8080

O servidor faz POST no emissor com {"token": "<token>"} e o header x-introspection-secret: <segredo>, esperando uma resposta no estilo RFC 7662:

{
  "active": true,
  "default_tenant": "algum-tenant",
  "allowed_tenants": ["algum-tenant", "outro-tenant"]
}

• active: false (ou erro de rede/HTTP) → token rejeitado (401).
• Resultado é cacheado em processo: 60s para token ativo, 15s para inativo — o emissor não é chamado a cada requisição.
• Fail-closed: se o emissor está fora do ar e não há nada em cache, a requisição recebe 503 (token issuer unavailable) em vez de passar sem validação. Uma entrada de cache expirada é servida como stale-on-error antes de negar um token que já era válido.
• Ordem de checagem, sem mudança de comportamento das outras fontes: GRKMEMORY_MCP_TOKENS (estático) → arquivo GRKAuth (GRKMEMORY_TOKENS_FILE) → introspecção.

Semântica de tenant (só para tokens introspectados): o token é privado por padrão. Chamada sem tenant_id explícito usa o default_tenant do token; tenant_id fora de allowed_tenants é rejeitado antes de tocar o storage; token sem default_tenant e sem tenant_id compatível falha fechado (nunca cai no GRKMEMORY_TENANT_ID do servidor, que não é checado contra allowed_tenants). Tokens estáticos e GRKAuth não mudam: continuam aceitando qualquer tenant_id que o chamador passar.

Conectando como consumidor (passo a passo)

1. Obtenha a URL e o seu token com quem opera o servidor. O token é definido por quem faz o deploy — não existe cadastro público. Se o operador é você mesmo: gere um valor forte (openssl rand -hex 24), adicione ao GRKMEMORY_MCP_TOKENS do host (CSV — um token por consumidor, para poder revogar individualmente) e reinicie o serviço; ou emita via grkmemory-token se o servidor usa arquivo GRKAuth.
2. Registre o servidor no seu Claude Code (vale para sessões locais, web e cloud):

   claude mcp add --transport http grkmemory https://<host>/mcp \
     --header "Authorization: Bearer <seu-token>"
   

   Sem CLI, o equivalente em .mcp.json:

   {
     "mcpServers": {
       "grkmemory": {
         "type": "http",
         "url": "https://<host>/mcp",
         "headers": { "Authorization": "Bearer <seu-token>" }
       }
     }
   }
   

3. Verifique: /mcp no chat deve listar grkmemory conectado com as 5 tools (memory_save, memory_search, memory_supersede, memory_get, memory_stats_tool).
4. Teste rápido: peça ao Claude "salve na memória: " e, numa sessão nova, "busque na memória: ".
5. Isolamento: em servidor compartilhado por vários times/projetos, passe tenant_id nas chamadas (ou combine um por consumidor) — memórias de tenants diferentes nunca se misturam.

Erros comuns: 401 = token errado/ausente no header; conexão recusada = servidor fora do ar ou URL sem o sufixo /mcp.

Interface de chat do claude.ai (sem Claude Code): o registro NÃO acontece dentro da conversa — a pessoa adiciona o conector em Settings → Connectors → Add custom connector. O diálogo pessoal só oferece campos de OAuth (sem campo de header); para esse caso use a URL com o token embutido:

https://<host>/t/<seu-token>/mcp

Deixe os campos de OAuth vazios e clique em Add. O /t/<token>/ é validado e removido pelo servidor antes de chegar ao endpoint MCP; header Authorization: Bearer continua sendo o caminho preferido onde houver campo para isso (Claude Code, SDKs, conectores de organização com static_headers). Como o token vive na URL, use um token por consumidor (revogável individualmente) e troque-o se a URL vazar em logs. Depois de habilitar o conector na conversa, as tools memory_* ficam disponíveis normalmente.

Limites por consumidor (quota e rate limit)

Num servidor remoto compartilhado, nada impedia um consumidor de saturar storage e embeddings de todos. Dois tetos opcionais, ambos desligados por default (sem as variáveis, o comportamento é exatamente o de antes):

export GRKMEMORY_RATE_LIMIT_PER_MIN=120          # requisições/min POR TOKEN
export GRKMEMORY_MAX_MEMORIES_PER_TENANT=10000   # memórias armazenadas POR TENANT

• Rate limit vive no middleware de auth: janela deslizante por token, resposta 429 com Retry-After: 60. Roda depois da validação do token — chavear por entrada não validada deixaria qualquer um encher o dicionário de contadores com tokens inventados, transformando a proteção no próprio vetor de exaustão de memória. As chaves são hash do token.
• Quota é checada antes da escrita em memory_save: ao atingir o teto, a tool recusa com erro claro (QuotaExceeded, erro de tool no protocolo MCP, não queda de transporte) em vez de gravar. Leitura não é afetada.
• Os dois chaveiam em dimensões diferentes porque é onde a informação existe: o transporte conhece o token, não o tenant (que depende dos argumentos da chamada); o teto de armazenamento é por natureza por tenant.
• O contador do rate limit é em memória do processo: com N instâncias, o teto efetivo é N × o valor configurado. Serve para impedir que um consumidor abafe os outros; um teto global exigiria contador compartilhado (Redis).

⚡ API assíncrona

Para uso em código assíncrono (ex.: AtendentePro) sem bloquear o event loop, use os métodos *_async, que executam a lógica síncrona em thread (ex.: asyncio.to_thread em Python 3.9+):

import asyncio
from grkmemory import GRKMemory

grk = GRKMemory()

async def main():
    results = await grk.search_async("IA")
    await grk.save_conversation_async([
        {"role": "user", "content": "Olá"},
        {"role": "assistant", "content": "Oi!"}
    ])
    response = await grk.chat_async("O que discutimos?")

asyncio.run(main())

Disponíveis: search_async, save_conversation_async, chat_async, chat_with_history_async. Com AuthenticatedGRK: search_async, save_conversation_async, chat_async (com checagem de permissão).

🔓 Modo Offline (Sem Token)

O modo offline usa MemoryRepository com enable_embeddings=False e serve como backend sem API key para testes ou ambientes restritos, usando apenas tags, entities e grafo semântico (sem embeddings). Você pode usar o MemoryRepository sem token/API key quando embeddings estão desabilitados:

from grkmemory import MemoryRepository

# Modo offline - não precisa de API key
repo = MemoryRepository(
    memory_file="memories.json",
    enable_embeddings=False  # ← Chave: desabilitar embeddings
)

# Funcionalidades disponíveis sem token:
# ✅ Salvar memórias
repo.save({
    "summary": "Conversa sobre Python",
    "tags": ["python", "programação"],
    "entities": ["Python"],
    "key_points": ["Linguagem interpretada"]
})

# ✅ Buscar por tags
results = repo.search("python", method="tags")

# ✅ Buscar por entities
results = repo.search("Python", method="entities")

# ✅ Buscar por grafo (sem embeddings)
results = repo.search("programação", method="graph")

# ❌ Busca por embedding requer API key
# results = repo.search("query", method="embedding")  # Retorna vazio sem API key

Nota: GRKMemory e MemoryConfig requerem API key. Apenas MemoryRepository com enable_embeddings=False funciona sem token.

💾 Salvando Conversas em JSON

O GRKMemory salva automaticamente as conversas em um arquivo JSON estruturado:

Estrutura do JSON

{
  "sessoes": [
    {
      "id": "sess_abc123",
      "timestamp": "2025-01-09T12:00:00",
      "summary": "Discussão sobre Python e IA",
      "tags": ["python", "ia", "programação"],
      "entities": ["Python", "OpenAI", "GPT"],
      "concepts": ["machine learning", "api"],
      "messages": [
        {"role": "user", "content": "..."},
        {"role": "assistant", "content": "..."}
      ]
    }
  ]
}

Estrutura do TOON (Token-Optimized Object Notation)

O mesmo conteúdo em TOON ocupa ~25% menos tokens, ideal para contexto de LLM:

sessoes[1]:
  - id: sess_abc123
    timestamp: "2025-01-09T12:00:00"
    summary: Discussão sobre Python e IA
    tags[3]: python,ia,programação
    entities[3]: Python,OpenAI,GPT
    concepts[2]: machine learning,api
    messages[2]{role,content}:
      user,Vamos falar sobre Python
      assistant,Claro! O que você quer saber?

Nota: TOON elimina chaves, colchetes e aspas redundantes, compactando listas e tabelas em notação posicional. Instale com pip install toon_format.

Usando o MemoryRepository diretamente

from grkmemory import MemoryRepository

# Inicializar repositório
repo = MemoryRepository(memory_file="minhas_memorias.json")

# Salvar memória estruturada
memoria = {
    "summary": "Conversa sobre Python",
    "tags": ["python", "programação"],
    "entities": ["Python", "VS Code"],
    "concepts": ["sintaxe", "bibliotecas"],
    "messages": [
        {"role": "user", "content": "Como instalar Python?"},
        {"role": "assistant", "content": "Baixe em python.org..."}
    ]
}
repo.save(memoria)

# Buscar memórias
resultados = repo.search("Python", method="tags")

📊 Métodos de Busca

Método	Descrição
graph	Grafo semântico (recomendado)
embedding	Similaridade vetorial
tags	Busca por tags
entities	Busca por entidades

# Busca por grafo semântico
results = secure.search("IA", method="graph")

# Busca por embedding
results = secure.search("machine learning", method="embedding")

📈 Estatísticas

# Estatísticas gerais
stats = secure.get_stats()
print(f"Total de memórias: {stats['total_memories']}")

# Estatísticas do grafo
graph_stats = secure.get_graph_stats()
print(f"Nós: {graph_stats['total_nodes']}")
print(f"Arestas: {graph_stats['total_edges']}")

📁 Estrutura do Projeto

GRKMemory/
├── grkmemory/              # 📦 Pacote principal
│   ├── core/               # Classes principais
│   ├── memory/             # Repositório de memória
│   ├── graph/              # Grafo semântico
│   ├── auth/               # Autenticação
│   └── utils/              # Utilitários
├── examples/               # 💡 Exemplos de uso
├── papers/                 # 📄 Documentação técnica
└── README.md

📚 Exemplos

Veja a pasta examples/ para exemplos completos:

Exemplo	Descrição
01_basic_usage.py	Uso básico
02_custom_config.py	Configuração personalizada
03_chatbot_with_memory.py	Chatbot com memória
04_graph_analysis.py	Análise do grafo
05_batch_processing.py	Processamento em lote
06_authentication.py	Uso com autenticação
07_storage_formats.py	Formatos de armazenamento (JSON/TOON)
08_azure_openai.py	Integração com Azure OpenAI
09_multi_tenant.py	Multi-tenant com user_id e session_id
10_async_usage.py	Uso da API assíncrona (search_async, chat_async)

🔬 Performance

Números de benchmarks internos (corpus de conversas reais; comparação: enviar o histórico completo na context window vs recall seletivo do GRKMemory). Reproduzíveis via repo.get_token_estimate() e os harnesses em tests/ — meça no seu corpus antes de assumir os mesmos ganhos:

Métrica	Histórico completo na context window	GRKMemory (recall seletivo)
Tokens/query	~50.000	~2.500 (~95% de economia neste corpus)
Latência de recuperação	cresce com o histórico	~constante (grafo/índice local)

✅ Qualidade

Sem selos — sinais verificáveis:

• Suite de testes: 249 testes rodando em CI a cada push/PR (Python 3.10–3.13), incluindo testes de integração contra Postgres/pgvector real e harnesses de regressão de recall (ablation/formula sweep) — veja tests/ e o workflow ci.yml.
• Coverage com gate mínimo configurado no CI.
• Em produção: a lib roda em serviços MonkAI de produção como camada de memória de agentes.
• Por que só wheels (sem sdist)? O código é compilado com Cython para proteção de propriedade intelectual — decisão deliberada, não descuido. A API pública, os testes e este README são o contrato auditável.

📞 Contato

Para obter seu token de acesso ou suporte:

📧 Email: [e-mail]
🌐 Site: www.monkai.com.br

📄 Licença

MIT License - veja LICENSE

👨‍💻 Autor

Arthur Vaz - MonkAI