Cria um preview server-side; não grava uma memória ativa.

Obtém exatamente o preview que será aprovado.

Cria proposta de rollback; nunca reativa a revisão histórica diretamente.

Cria memória a partir de um Pull Request (PR + work item linkados).

Use when: persistir o que um PR mudou e por quê; ligar PR a work item. Do NOT use for: regra/decisão genérica (memory.upsert); evento sem PR (memory.episode.create). pr_url e work_item_url são obrigatórios. Example: memory.pr.create(project='DecisionsSearch', repo='org/repo', pr_number=42, title='Add HyDE', summary='...', changed_files=[...], pr_url='...', work_item_url='...').

Consulta memórias de PR por projeto, repo ou arquivo alterado.

Liga um PRMemory a um MemoryItem (IMPLEMENTS, EVIDENCES, MODIFIES).

Lista MemoryItems linkados a um PR.

Lista PRs linkados a um MemoryItem.

Exporta catálogo do grafo como bundle CSV.

Importa catálogo do grafo a partir de bundle CSV.

Cria um novo projeto no catálogo do grafo.

Atualiza dados de um projeto existente no catálogo.

Lista todos os projetos do catálogo.

Cria uma nova categoria no catálogo do grafo.

Atualiza dados de uma categoria existente no catálogo.

Cria um novo domínio no catálogo do grafo.

Atualiza dados de um domínio existente no catálogo.

Cria relação entre dois nós do catálogo do grafo.

Remove relação entre dois nós do catálogo do grafo.

Cria memória estruturada com categoria explícita (DesignRule, BusinessRule, ArchitecturalDecision, DesignPattern).

Use when: o usuário dá uma regra/decisão/padrão já classificável e você sabe a categoria. Do NOT use for: salvar rápido sem categoria (memory.upsert); PR (memory.pr.create); passo-a-passo (memory.procedure.create); evento (memory.episode.create). ArchitecturalDecision exige alternatives_considered. Example: memory.manual.create(project='ExampleProject', category='DesignRule', title='Cache key', summary='pj:cache:{tenant}:{entity}'). Omit project to derive it from the agent workspace folder.

Busca semântica + grafo de memórias de um projeto (o jeito padrão de RECUPERAR).

Use when: responder "como/por que/qual" sobre um projeto; recuperar regras, decisões e padrões. Do NOT use for: pegar 1 memória por id (memory.get); ponto no tempo (memory.query_at); montar pacote de contexto pra uma task (memory.context). hyde=True força expansão HyDE (queries curtas/vagas; +1 LLM call). Omit project to query only the project resolved from the agent workspace folder.

Lista memórias similares (>= threshold). Chame ANTES de criar p/ evitar duplicatas.

text = título + summary da memória que você pretende criar. Use o resultado para decidir entre criar nova (memory.upsert/memory.manual.create) ou refinar uma existente (search-before-write, S3). Default 0.85 calibrado para o MiniLM local (cosine fica ~0.86 em quase-idênticos); suba para ~0.92 com embeddings maiores. Omit project to use the agent workspace folder.

Recupera UMA memória pelo memory_id exato (lookup direto, sem busca).

Use when: você já tem o memory_id (veio de memory.query/find_duplicates) e quer o registro completo. Do NOT use for: busca por tema (memory.query). Example: memory.get(memory_id='c3f814b1babebd35').

Consulta memórias que estavam ATIVAS num instante passado (bitemporal, ISO 8601).

Use when: auditoria / "o que valia em "; reconstruir estado histórico. Do NOT use for: estado atual (memory.query). Example: memory.query_at(project='CORE', point_in_time='2026-01-01T00:00:00Z').

Cria/atualiza memória canônica de forma idempotente (o jeito padrão de SALVAR).

Use when: persistir rápido uma regra/decisão/fato técnico; o admission decide create vs refine. Do NOT use for: PR (memory.pr.create); passo-a-passo (memory.procedure.create); evento único (memory.episode.create); texto cru pra extração (memory.ingest_raw). Chame memory.find_duplicates ANTES p/ evitar duplicata. Example: memory.upsert(project='ExampleProject', category='DesignRule', title='Cache key', summary='pj:cache:{tenant}:{entity}'). Omit project to derive it from the agent workspace folder.

Ingere texto CRU e deixa o pipeline extrair/classificar/persistir sozinho.

Use when: você tem um blob não-estruturado (log, mensagem, doc) e quer que o sistema decida o que virar memória. Do NOT use for: conteúdo já estruturado que você sabe classificar (memory.upsert/memory.manual.create). Mais caro (LLM de extração). Example: memory.ingest_raw(source_kind='slack', payload='', project_hint='CORE'). Omit project_hint to derive the project from the agent workspace folder.

Lista eventos da landing zone para inspeção.

Define peso manual de uma memória e recalcula peso efetivo.

Depreca memória e opcionalmente liga DEPRECATES para substituta.

Cria relação semântica entre duas memórias.

Dispara consolidação imediata ou diferida.

Registra feedback de uso para telemetria.

Monta um PACOTE de contexto (regras/padrões/decisões) ANTES de começar uma task.

Use when: vai iniciar um trabalho num projeto/domínio e quer o conhecimento relevante pré-carregado de uma vez. Do NOT use for: responder 1 pergunta pontual (memory.query); destilar pós-task (memory.reflect). Example: memory.context(project='ExampleProject', domain='cache').

Verifica consistência entre Neo4j e Qdrant e remove vetores órfãos.

Extrai conhecimento de uma task CONCLUÍDA e persiste (loop de pós-task).

Use when: terminou um trabalho e quer destilar o que foi aprendido em memória durável. Do NOT use for: RECUPERAR conhecimento (memory.query); pré-task (memory.context). outcome: 'completed' | 'failed' | 'partial'. Example: memory.reflect(task_description='Implementei HyDE opt-in', changes='...', project='DecisionsSearch').

Verifica memória durável a partir da sessão e do commit/PR atual.

Use depois de concluir um commit ou PR quando houver contexto da sessão para explicar intenção e impacto. O LLM pode retornar no_memory; essa resposta é correta e não cria candidato. O resultado ainda passa pelos gates de admissão e, em dry_run, apenas mostra propostas. O hook nunca deve ser usado para bloquear o commit.

Cria um PROCEDIMENTO reutilizável (passo-a-passo) para um tipo de tarefa.

Use when: o conhecimento é uma sequência de passos repetível (runbook, how-to). Do NOT use for: regra/fato estático (memory.upsert); registro de um evento único (memory.episode.create). Example: memory.procedure.create(project='CORE', task_type='deploy', steps=['build', 'migrate', 'rollout']).

Consulta procedimentos armazenados por tipo de tarefa.

Registra um EPISÓDIO: o que foi feito numa task específica e o resultado.

Use when: capturar um acontecimento único (o que tentei, deu certo/errado, lições). Do NOT use for: conhecimento atemporal/regra (memory.upsert); passo-a-passo reutilizável (memory.procedure.create). Example: memory.episode.create( project='CORE', task_description='Migrei PLD', outcome='completed', lessons=['...']).

Consulta memórias episódicas por projeto, outcome ou tag.

Ingesta um erro e dispara pipeline de investigação automaticamente.

Lista erros ingeridos, opcionalmente filtrando por service ou error_type.

Recupera detalhes da investigação de um erro.

Lista jobs agendados (consolidação, summary, etc.).

Executa um job agendado imediatamente.

Historico de execucoes de um job.

Full scan of all PRs from configured GitHub repos + Shortcut cards. Imports everything, not just recent.