# Memória de aprendizados



<ToolHero tool="memoria-de-aprendizados" />

## Como funciona

Um aprendizado é um texto curto com um `kind`, ligado a um `project`:

| `kind`       | Para guardar                                 |
| ------------ | -------------------------------------------- |
| `pitfall`    | Armadilhas e erros que não devem se repetir. |
| `decision`   | Decisões tomadas e o motivo.                 |
| `convention` | Convenções do projeto.                       |
| `howto`      | Como fazer algo (rodar, publicar, depurar).  |
| `other`      | O que não cabe nos outros.                   |

Os aprendizados ficam numa [base de conhecimento](/ferramentas/base-de-conhecimento) chamada `agent-learnings`, **criada sozinha** na primeira gravação. O `recall` faz uma busca semântica pela tarefa e devolve só os itens do `project` pedido, com a `score` de cada um.

Também está disponível no [MCP](/agentes-de-ia) como `learning_save`, `learning_recall` e `learning_forget` (toolset `learnings`).

<EndpointList tool="memoria-de-aprendizados" />

## Duplicados e ingestão assíncrona

* **Deduplicação:** o `save` compara por hash e por similaridade semântica. Se já existe um aprendizado igual ou parecido, nada novo é gravado e a resposta traz `duplicate_of` com o id do existente.
* **Ingestão assíncrona:** o texto é indexado em segundo plano. Um `recall` logo depois de um `save` pode ainda não trazer o item; tente de novo em alguns segundos.

## Custos

A cobrança é a da [base de conhecimento](/ferramentas/base-de-conhecimento): o `save` como a ingestão (por trecho), o `recall` como a busca (franquia diária + blocos) e o armazenamento por dia. Esquecer é grátis. A memória segue as mesmas regras de liberação da base de conhecimento (`rag.disabled` e demais erros `rag.*`).

## Endpoints

### Salvar aprendizado

<Endpoint id="learnings.save" example={{ body: `{ "project": "respawn-tech-docs", "kind": "pitfall", "text": "O check:backend lê ../respawn-tech-backend; rode só com o backend já junto.", "source": "conversa de 06/10" }` }}>
  `project`, `kind` e `text` são obrigatórios; `source` é opcional e diz de onde veio. A resposta traz o `id` do aprendizado ou, se for repetido, `duplicate_of`.
</Endpoint>

### Recuperar aprendizados

<Endpoint id="learnings.recall" example={{ body: `{ "project": "respawn-tech-docs", "task": "rodar os checks antes de abrir o PR", "top_k": 5 }` }}>
  `project` e `task` são obrigatórios; `top_k` limita quantos itens voltam. Cada item traz `id`, `kind`, `text`, `source` e `score`. Lembre que a ingestão é assíncrona: um item recém-salvo pode ainda não aparecer.
</Endpoint>

### Esquecer aprendizado

<Endpoint id="learnings.forget" />