Voce e um agente de AI.
Esta e sua API de memoria.
Engram te da memoria persistente via 17 ferramentas MCP. Armazene o que aprender, lembre o que sua equipe sabe, reporte o que funcionou.
# 1. Teste grátis, sem e-mail nem chave API npx -y engram-tools@latest --setup # 2. Reinicie Claude, Codex, Cursor, Gemini ou Antigravity, Windsurf ou VS Code # 3. Cole isto como instruções do agente, não como comandos shell Chame engram_start com project, repo, role, market, stack e task. Antes de escolher uma abordagem, chame engram_recall ou engram_cross_pollinate. Se o contexto foi compactado ou retomado, chame engram_rehydrate antes de continuar. Use engram_reflect como checkpoint após fases importantes ou antes de passar o trabalho.
Configuracao para sua ferramenta
// ~/.claude/mcp.json{"mcpServers": {"engram": {"command": "npx","args": ["-y", "engram-tools@latest", "mcp"],"env": {"ENGRAM_API_URL": "https://api.engram.tools"}}}}
Um agente pode testar sem e-mail?
Sim. O pacote npm inicia um teste gratuito isolado. Use connect depois para verificar um e-mail e manter as memórias. Qualquer pagamento exige autorização humana.
Faça a próxima sessão lembrar
Teste uma decisão real do projeto entre duas sessões.
Com permissão para instalar ferramentas, execute npx -y engram-tools@latest --setup para o teste npm gratuito. Não precisa de e-mail nem chave API. Mantenha o espaço existente.
Reconecte o cliente de desenvolvimento. Chame engram_start com o repositório e a tarefa reais.
Durante o trabalho, salve uma decisão confirmada e seu motivo com engram_store. Não guarde segredos.
Abra uma nova sessão no mesmo repositório. Peça ao agente engram_recall para recuperar a decisão e o motivo.
Confira a memória fonte no projeto atual. Informe sua utilidade com engram_report_outcome.
Para manter o espaço de teste, execute npx -y engram-tools@latest connect e confirme seu e-mail. As memórias continuam no mesmo espaço.
Primeira sessão
Chame engram_start para minha tarefa real neste repositório. Depois salve uma decisão confirmada e o motivo com engram_store. Preserve o espaço existente; não guarde segredos nem invente fatos de demonstração.
Próxima sessão
Recupere com engram_recall a decisão e o motivo da sessão anterior. Mostre a memória fonte, confira no projeto atual e continue. Informe se ajudou.
// Quando usar cada ferramenta
Não preencha formulário humano. Treine o loop de memória.
Quando uma memória ajuda, está desatualizada ou veio fora de contexto, reporte pelas ferramentas. Esse sinal melhora o ranking futuro.
Aprendizado Entre Sessoes
Voce corrige um bug dificil na sessao 1. Sessao 2, o mesmo padrao aparece em outro arquivo. Voce lembra da correcao instantaneamente.
Transferencia de Conhecimento da Equipe
Um agente Cursor no frontend descobre que a API espera snake_case. Um agente Claude Code no backend aprende isso sem ninguem contar.
Aplicacao de Convencoes
Antes de escrever codigo, voce lembra as convencoes do projeto. "Use Zod para validacao, nao Joi." Voce segue o padrao da equipe automaticamente.
Memória, atualidade e feedback
O funcionamento prático das ferramentas. As tabelas de parâmetros vêm do esquema MCP. Os exemplos de resposta são trechos HTTP sem dados sensíveis. O MCP retorna JSON, Markdown ou confirmações curtas por text/format; confira format antes de interpretar.
Escolha a ferramenta conforme a necessidade
Começar o trabalho em um repositório
engram_startVisão do espaço e memória relevante
Responder a uma pergunta concreta
engram_recallMemórias ordenadas para essa pergunta
Mudar de tarefa com o contexto preservado
engram_smarterResumo focado na nova tarefa
Retomar após perder o contexto
engram_rehydrateRecuperação segura do diário e apoio na memória atual
Registrar um marco do trabalho
engram_reflectCheckpoint; a sessão continua aberta
O cliente npm pode iniciar um teste gratuito isolado sem e-mail nem chave API. As conexões OAuth remotas verificam o e-mail. Nunca invente credenciais. repo é um filtro no espaço autorizado, não uma permissão para acessar outro espaço.
Use engram_start ao começar, engram_recall para uma pergunta, engram_smarter ao mudar de tarefa e engram_rehydrate após compactação do contexto ou interrupção. Smarter busca memória duradoura para a nova tarefa; não reconstrói o diário anterior. Ambos podem registrar eventos de sessão. Rehydrate pode ler sessões fechadas ou o histórico de colegas, mas não reabri-las nem escrever nelas. engram_reflect mantém a sessão aberta; engram_close_session a encerra explicitamente.
Os padrões focused são start=8, recall=5, smarter=5 e cross_pollinate=5 registros. Com deep, são 16, 12, 12 e 12, respectivamente. Um limit explícito substitui esses valores dentro do máximo da ferramenta. Sem include_skills explicitamente true ou false, os guias são inferidos das palavras-chave da tarefa.
Rehydrate usa outro orçamento: depth=brief retorna até 12 eventos e 2 resumos; standard, 30 e 4; full, 60 e 8. Não aceita limit nem os valores de busca focused/deep.
Se recall retornar count=0, diga que nenhuma memória correspondente foi encontrada. Confira repo e a consulta, reformule ou use depth=deep quando fizer sentido. Mais resultados não tornam relevante uma informação alheia. Use cross_pollinate se outro repositório provavelmente contém uma lição transferível. get_context serve à inspeção deliberada por categoria, não é o próximo passo automático de toda busca vazia.
Separe regras de fatos que podem mudar
Prefira um fato que possa ser mantido separadamente por memória. Uma regra de autorização e um estado de implantação devem ter IDs próprios. Para uma unidade, use type, content e claim opcional; para 1–32 unidades independentes, use claims, cada uma com type, content e claim. Não misture os formatos. Memórias antigas sem tipagem continuam legacy_unassessed; adicionar metadados não prova que uma nota contém só um fato.
type é a categoria de busca, como CONVENTION ou SOLUTION; claim.kind distingue rule, decision, state, lesson e reference. Só state possui stage: proposed, implemented, tested ou deployed. Exige observed_at em ISO com fuso horário, no máximo um minuto à frente do relógio do servidor. UTC e deslocamentos explícitos são aceitos; mantenha o relógio do cliente sincronizado. tested/deployed também exigem evidence, fornecida pelo agente, sem verificação independente pelo Engram. review_after é opcional e não pode anteceder observed_at. É uma data de revisão, não expiração automática nem permissão para retirar uma regra.
kind=rule não concede autoridade humana nem substitui instruções atuais. Use supersedes_memory_ids e change_reason somente para substituição verificada. Uma divisão legada usa split_from com memory_id e content_sha256; por padrão só visualiza o plano. Aplique apenas com dry_run=false e a confirmação recebida split:<id>:<plan_hash>. Partes históricas continuam históricas; não copie votos de sucesso para fatos novos sem relação.
Exemplo: substitua os marcadores pelos valores realmente retornados.
{
"claims": [
{
"type": "CONVENTION",
"content": "Deployment requires explicit owner approval.",
"claim": {
"kind": "rule"
}
},
{
"type": "SOLUTION",
"content": "The OAuth callback fix passed the isolated test suite.",
"claim": {
"kind": "state",
"stage": "tested",
"observed_at": "2026-11-15T09:00:00Z",
"evidence": "Commit abc1234; isolated OAuth regression receipt"
}
}
]
}Revise uma nota mista sem perder a regra válida
Se uma nota junta uma regra válida e um estado de publicação obsoleto, não retire tudo só para esconder esse estado. Revise cada fato independente. Mantenha a regra ativa e marque como histórica apenas a parte obsoleta de claims. O criador ou proprietário humano pode dividir a nota; a fonte deve ser privada, ativa e ainda não declarada como claim.
Para visualizar o plano, envie claims e split_from juntos. Calcule content_sha256 sobre o texto exato armazenado, não uma versão resumida ou paráfrase. A prévia não grava memórias. Confira claims, active_claims e historical_claims antes de aplicar. O exemplo é pseudocódigo do SDK MCP: source é o registro real e claims sua lista revisada; historical:true só nas partes obsoletas.
Reenvie a fonte e o plano sem mudanças com dry_run=false e a confirmation da prévia copiada exatamente. Não invente uma confirmação. Fonte ou plano alterados exigem nova prévia. O original fica no histórico; as unidades novas recebem IDs separados sem herdar votos. A prévia verifica a estrutura da gravação, não a veracidade da revisão.
Exemplo: substitua os marcadores pelos valores realmente retornados.
const plan = {
split_from: {
memory_id: source.id,
content_sha256: sha256(source.content) // SHA-256 hex of exact text
},
claims // reviewed independent units; obsolete pieces use historical: true
};
const result = await client.callTool({ name: "engram_store", arguments: plan });
if (result.isError) throw new Error("Split preview failed");
if (result.structuredContent?.format !== "json") throw new Error("Expected JSON preview");
const preview = JSON.parse(result.structuredContent.text);
// Review preview.claims, active_claims and historical_claims before applying.
await client.callTool({
name: "engram_store",
arguments: { ...plan, dry_run: false, confirmation: preview.confirmation }
});Útil não significa verificado nem atual
success=true significa que a memória ajudou na tarefa. Não prova que ainda seja verdadeira, esteja em produção ou que toda frase de uma nota antiga mista esteja correta. trust=validated e confidence são rótulos de compatibilidade para utilidade relatada, não verificação independente. Leia claim.stage, observed_at, evidence e last_outdated_report_at; confira fatos críticos no código e no sistema atuais.
A relevância inicial é relevant, irrelevant ou uncertain. A utilidade real é helpful, unhelpful, not_used ou not_evaluated. Apenas helpful/unhelpful cria voto e altera confidence. Um resultado pode ser irrelevant e not_used sem voto negativo de uso. Sem feedback, fica não avaliado. Notas de relevância e evidências de uso são separadas.
Os sinais useful/noisy/stale/missing_context/too_long em engram_reflect.feedback ou POST /api/v1/feedback avaliam o Engram como produto. São separados dos resultados de cada memória e não alteram a confidence individual.
Vincule o feedback à consulta exata e trate repetições
retrieval_id identifica a apresentação registrada de uma lista de resultados; session_id identifica um diário. Mantenha cada retrieval_id com sua lista, sobretudo se a mesma memória aparecer em consultas paralelas. retrieval_id null indica que não há atribuição exata nessa resposta. Fontes antigas ou fechadas podem receber feedback explícito se recibo, memória e solicitante continuarem acessíveis; não reabra o diário.
Para um uso real, chame engram_report_outcome com memory_id, success e retrieval_id. Use outcomes para até 20 pares consulta/memória únicos. Também é possível anexar os mesmos itens como pending_feedback à próxima chamada start, recall, smarter, store, reflect, cross_pollinate, get_context, skill ou report_outcome. Exige outcome:write e não consome quota adicional de chamadas. Omita o que não consegue avaliar, em vez de inventar um julgamento.
Para repetir um relato exato, envie os mesmos retrieval_id, memory_id e campos de uso. Engram responde duplicate=true sem novo voto. duplicate é campo da resposta, não entrada; não existe sinalizador retry. A repetição não é erro 409; mudar um voto já gravado retorna 409. Sem retrieval_id, o formato antigo escolhe a apresentação mais recente dessa memória para o membro e espaço autenticados nas últimas 24 horas. session_id restringe a busca ao diário. Repetições antigas podem adicionar votos; atribuição inferida não é exata. Um uso realmente novo deve ter uma nova apresentação.
O lote de feedback é confirmado antes da ação principal. Confira feedback_receipt mesmo se ela falhar: o feedback pode ter sido salvo. MCP remoto e cliente npm preservam o recibo nos erros. Falha com feedback já confirmado não é repetida automaticamente; a ação principal ainda pode não ser idempotente. Em reflect.used_memories, cada item de um lote exato atômico de até 20 deve ter retrieval_id; mantenha o formato antigo em outra reflexão. Aprendizado ou checkpoint posterior pode falhar; feedback_receipt mostra os resultados aceitos.
Exemplo: substitua os marcadores pelos valores realmente retornados.
{
"repo": "example",
"query": "Which deployment rule applies?",
"pending_feedback": [
{
"retrieval_id": "<id from the previous result list>",
"memory_id": "<memory in that list>",
"relevance": "irrelevant",
"usefulness": "not_used"
}
]
}Recomendado: resultados ligados à consulta exata (argumentos de engram_reflect)
{
"store": false,
"summary": "Applied the recalled approval rule.",
"used_memories": [
{
"retrieval_id": "<id from that result list>",
"memory_id": "<memory in that list>",
"success": true,
"detail": "Checked owner approval before releasing."
}
]
}Só para compatibilidade: reflexão legada separada (argumentos de engram_reflect)
{
"store": false,
"summary": "Reported a use without a retained query receipt.",
"used_memories": [
{
"memory_id": "<accessible memory id>",
"success": true,
"detail": "This use has inferred attribution, not an exact query link."
}
]
}Retirada, exclusão permanente e recuperação segura
engram_retract_memory retira conhecimento privado de forma reversível; pode ser usado pelo criador ou proprietário humano. engram_restore_memory exige um registro retirado ainda preservado e verifica quota e substituições confirmadas. Nem gravar o mesmo texto nem rehydrate o restaura silenciosamente. Registros excluídos não podem ser restaurados.
Um token OAuth não pode visualizar nem executar a exclusão permanente, mesmo que o membro seja OWNER. Ambas as operações exigem o caminho separado da credencial API do proprietário humano. Não obtenha nem substitua a chave dele para contornar OAuth. engram_delete_memory mostra o impacto por padrão; execute só com dry_run=false e confirmation=delete:<exact memory_id>. Remove a memória ativa, cópias ligadas conhecidas e texto livre dos diários afetados. Contexto já enviado a clientes, registros independentes, paráfrases sem vínculo, provedores e backups ficam fora dessa exclusão direcionada.
A busca de sessões oculta tarefas ligadas a conhecimento retirado, expirado ou excluído. Se não for possível reconstruir o diário com segurança, use memória atual segura ou abra um diário limpo com engram_start(new_session=true); não contorne a ocultação. Restaurar uma fonte preservada pode devolver acesso ao seu histórico seguro.
Referencia API
Documentacao completa para todas as 17 ferramentas MCP.
engram_startInicie o trabalho em um repositório. No início de uma sessão relevante; use rehydrate para recuperar contexto perdido. Guia do espaço, ID de sessão e memórias relevantes.
{"agent_tool": "codex","project": "English.cash","repo": "english.cash","role": "full-stack product engineer","market": "English learning","task": "fix guest practice so it uses the same API path as paid practice","stack": ["Next.js", "TypeScript", "PostgreSQL", "LLM router"]}
engram_rehydrateRetome após perder contexto. Antes de continuar após compactação, resumo ou interrupção. Checkpoints, decisões e pendências recuperáveis com segurança; histórico fechado não reabre.
{"agent_tool": "codex","project": "Engram","repo": "engram","task": "continue mobile Safari chat fix after context compaction","reason": "chat was compacted and only a short summary remains","depth": "standard"}
engram_smarterReoriente o contexto ao mudar de tarefa. Na mesma sessão ativa; não reconstrói um diário perdido. Memórias e guias para a nova tarefa.
{"context": "Next.js 16 mobile Safari chat widget overflows when keyboard opens","repo": "engram","file": "web/src/components/ChatWidget.tsx","include_skills": true}
engram_cross_pollinateReaproveite lições de outros repositórios. Se outro projeto provavelmente resolveu um problema parecido. Lições com origem e aplicabilidade; o destino não é pesquisado como fonte.
{"target_repo": "skillbridge-monorepo","context": "Add team invite flow with owner/admin permissions and email delivery","source_repos": ["engram", "evimibul"],"include_public": true,"limit": 5}
engram_storeSalve conhecimento mantido de forma independente. Após confirmar uma lição; separe regras de estados temporários. Um ID ou IDs separados para claims; a divisão visualiza antes de aplicar.
{"type": "SOLUTION","content": "Mobile Safari chat panels should not autofocus inputs. Size the fixed panel from visualViewport, use 16px input text, and assert bounds after typing.","tags": ["ios", "safari", "mobile", "chat-widget"],"repo": "engram","agent_tool": "codex","context": {"file": "web/src/components/ChatWidget.tsx","platform": "ios-safari"}}
engram_recallBusque uma resposta concreta antes de decidir. Para uma pergunta, decisão anterior ou erro específico. Memórias ordenadas e retrieval_id se disponível; diga quando não houver correspondência.
{"query": "Stripe checkout succeeded but workspace plan still free after webhook","repo": "engram","type": "SOLUTION","limit": 3}
engram_report_outcomeRelate a utilidade de uma memória. Depois do uso real com retrieval_id; irrelevância não é falha de uso. Repetir o resultado exato não adiciona voto; alterá-lo dá 409. O legado infere até 24 horas e pode adicionar votos.
{"retrieval_id": "retrieval_id_from_that_recall","memory_id": "cmqstripeplan123","success": true,"detail": "The recalled webhook transaction pattern fixed the dashboard plan mismatch in production."}
engram_reflectRegistre um checkpoint do trabalho. Após uma etapa importante, vários usos ou antes da passagem; não é temporizador. Aprendizados, resultados e checkpoint. store=false não impede todas as gravações; a sessão continua aberta.
{"repo": "engram","task": "Fix mobile Safari chat overflow and close behavior","summary": "Chat panel now sizes from visualViewport, avoids mobile autofocus, uses 16px input text, and close restores the launcher.","used_memories": [{"memory_id": "cmqioschat123","success": true,"detail": "The iOS visualViewport gotcha pointed to the correct fix."}],"learnings": [{"type": "SOLUTION","content": "For mobile fixed panels, compute bounds from visualViewport and verify after focusing an input; CSS dvh alone may not catch layout viewport offset.","tags": ["mobile", "safari", "visualViewport"]}]}
engram_get_contextInspecione a memória por categoria. Para auditoria ou depuração deliberada, não após toda busca vazia. Categorias relevantes; o escopo pode ampliar se o repo não tiver correspondências.
{"repo": "engram","task": "Polish localized documentation without breaking rendered pages"}
engram_skillCarregue um guia passo a passo. Para procedimentos repetíveis, não um fato específico do projeto. Passos ou nomes disponíveis; desconhecido dá count=0. Não instala nem executa nada.
{"skill": "security-audit"}
engram_proofVeja evidências de uso do espaço. Para revisão do produto ou administração, fora do fluxo normal de código. Dados de memória, uso, ativação e benchmarks.
engram_proof()
engram_setupConsulte configuração e orientação do espaço. Para entender a conexão; comece o trabalho diário com start. Espaço, ferramentas e próxima ação útil.
{"agent_tool": "claude-code"}
engram_list_sessionsEncontre o diário exato. Se houver várias sessões; workspace descobre metadados compartilhados. Metadados paginados e next_cursor; tarefas ligadas a conhecimento retirado ficam ocultas.
{ "repo": "engram", "scope": "mine", "limit": 20 }
engram_close_sessionFinalize uma sessão específica. Opcional no fim ou na passagem; exige propriedade e session:write. Checkpoint e encerramento atômicos; repetir devolve o mesmo recibo. Memórias e histórico somente leitura ficam preservados.
{ "session_id": "example-session", "summary": "Tests passed; deployment awaits approval." }
engram_retract_memoryRetire uma memória privada reversivelmente. Criador ou proprietário humano com memory:write para orientação inválida. Preserva conteúdo; oculta busca, padrões dependentes e diários relacionados. Repetir não cria efeito novo.
{ "memory_id": "example-memory", "reason": "This advice needs revalidation." }
engram_restore_memoryReative uma memória retirada após revisão. Criador ou proprietário humano; aplicam-se quota e substituições confirmadas. Preserva ID e texto. Uma ativa não muda; excluída não volta. Store não restaura.
{ "memory_id": "example-memory" }
engram_delete_memoryInspecione e execute exclusão permanente. Até a prévia exige API do proprietário humano OWNER; OAuth não basta. Executar exige confirmation exata. Remove memória ativa, derivados conhecidos e texto dos diários afetados; mantém recibo mínimo. Exclui registros independentes, paráfrases soltas, contexto do cliente, backups e provedores.
{ "memory_id": "example-memory", "dry_run": true }
Tipos de Memoria
CONVENTIONPadroes de codigo e regras da equipe
"Always use Prisma migrations"
PATTERNAbordagens recorrentes e templates
"API routes use cached() wrapper"
GOTCHACoisas que quebram ou surpreendem
"Neon requires SSL in production"
SOLUTIONCorrecoes que funcionaram
"Fix: add pooler to connection string"
ARCHITECTUREDecisoes de design de sistema
"Search uses Haversine + bbox"
DEPENDENCYInfo de bibliotecas e versoes
"Prisma 7 needs adapter pattern"
// Endpoint legivel por maquina
GET https://engram.tools/api/v1/capabilitiesRetorna JSON com ferramentas suportadas, tipos de memoria, limites de taxa e precos - projetado para consumo programatico.