> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mka1.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Memória de longo prazo

> Use a ferramenta de histórico para dar memória persistente aos modelos entre sessões, permitindo a recuperação de conversas passadas por usuário final.

A ferramenta `history` fornece aos modelos uma memória de longo prazo que persiste entre sessões.
Quando ativada, cada par de solicitação-resposta é armazenado e indexado automaticamente.
O modelo pode então buscar semanticamente interações passadas para recuperar informações de conversas anteriores.

## Como funciona

1. Adicione `{ type: "history" }` ao array `tools` em sua solicitação
2. O modelo recebe uma função `history` que pode ser chamada com uma consulta de busca
3. Conversas passadas são pesquisadas usando embeddings vetoriais para similaridade semântica
4. Após cada resposta ser concluída, a mensagem do usuário e a resposta do assistente são armazenadas automaticamente em segundo plano

A memória é **definida por usuário final** — cada ID de usuário `X-On-Behalf-Of` possui um histórico isolado. Usuários finais diferentes não podem ver o histórico uns dos outros.

## Ative a ferramenta de histórico

<CodeGroup>
  ```bash CLI theme={null}
  mka1 llm responses create \
    --model meetkai:functionary-pt \
    --body '{
      "input": "Lembre-se disto: minha cor favorita é azul.",
      "tools": [{ "type": "history" }],
      "store": true
    }' \
    -H 'X-On-Behalf-Of: <end-user-id>'
  ```

  ```ts MKA1 SDK theme={null}
  import { SDK } from '@meetkai/mka1';

  const mka1 = new SDK({
    bearerAuth: `Bearer ${YOUR_API_KEY}`,
  });

  const result = await mka1.llm.responses.create({
    model: 'meetkai:functionary-pt',
    input: 'Lembre-se disto: minha cor favorita é azul.',
    tools: [{ type: 'history' }],
    store: true,
  }, { headers: { 'X-On-Behalf-Of': '<end-user-id>' } });
  ```

  ```ts OpenAI SDK theme={null}
  import OpenAI from 'openai';

  const openai = new OpenAI({
    apiKey: '<mka1-api-key>',
    baseURL: 'https://apigw.mka1.com/api/v1/llm/',
    defaultHeaders: { 'X-On-Behalf-Of': '<end-user-id>' },
  });

  const response = await openai.responses.create({
    model: 'meetkai:functionary-pt',
    input: 'Lembre-se disto: minha cor favorita é azul.',
    tools: [{ type: 'history' }],
    store: true,
    stream: false,
  });
  ```

  ```csharp C# SDK theme={null}
  using MeetKai.MKA1;
  using MeetKai.MKA1.Types.Components;

  var sdk = new SDK(
      bearerAuth: $"Bearer {YOUR_API_KEY}",
      serverUrl: "https://apigw.mka1.com"
  );

  var res = await sdk.Llm.Responses.CreateAsync(new ResponsesCreateRequest()
  {
      Model = "meetkai:functionary-pt",
      Input = ResponsesCreateRequestInput.CreateStr(
          "Lembre-se disto: minha cor favorita é azul."),
      Tools = new List<ResponsesCreateRequestTool>
      {
          ResponsesCreateRequestTool.CreateHistoryToolDefinition(new HistoryToolDefinition()),
      },
      Store = true,
  });
  ```

  ```python Python SDK theme={null}
  from mka1 import SDK

  sdk = SDK(bearer_auth="Bearer YOUR_API_KEY")

  result = sdk.llm.responses.create(
      model="meetkai:functionary-pt",
      input="Lembre-se disto: minha cor favorita é azul.",
      tools=[{"type": "history"}],
      store=True,
  )
  ```

  ```bash bash theme={null}
  curl https://apigw.mka1.com/api/v1/llm/responses \
    --request POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <mka1-api-key>' \
    --header 'X-On-Behalf-Of: <end-user-id>' \
    --data '{
      "model": "meetkai:functionary-pt",
      "input": "Lembre-se disto: minha cor favorita é azul.",
      "tools": [{ "type": "history" }],
      "store": true
    }'
  ```
</CodeGroup>

Defina `store: true` para que a conversa seja persistida e disponível para recuperação futura.

## Recupere informações de uma sessão anterior

Em uma solicitação posterior — mesmo minutos, horas ou dias depois — o modelo pode buscar em seu histórico para encontrar interações passadas relevantes. O modelo decide quando chamar a ferramenta de histórico com base na pergunta do usuário.

<CodeGroup>
  ```bash CLI theme={null}
  mka1 llm responses create \
    --model meetkai:functionary-pt \
    --body '{
      "input": "Qual é a minha cor favorita?",
      "tools": [{ "type": "history" }],
      "store": true
    }'
  ```

  ```ts MKA1 SDK theme={null}
  // Em uma nova sessão, o modelo pode recuperar conversas passadas
  const result = await mka1.llm.responses.create({
    model: 'meetkai:functionary-pt',
    input: 'Qual é a minha cor favorita?',
    tools: [{ type: 'history' }],
    store: true,
  }, { headers: { 'X-On-Behalf-Of': '<end-user-id>' } });

  // O modelo chama a ferramenta de histórico, encontra a conversa anterior,
  // e responde: "Sua cor favorita é azul."
  ```

  ```ts OpenAI SDK theme={null}
  const response = await openai.responses.create({
    model: 'meetkai:functionary-pt',
    input: 'Qual é a minha cor favorita?',
    tools: [{ type: 'history' }],
    store: true,
    stream: false,
  });

  // O modelo chama a ferramenta de histórico, encontra a conversa anterior,
  // e responde: "Sua cor favorita é azul."
  ```

  ```csharp C# SDK theme={null}
  // Em uma nova sessão, o modelo pode recuperar conversas passadas
  var res = await sdk.Llm.Responses.CreateAsync(new ResponsesCreateRequest()
  {
      Model = "meetkai:functionary-pt",
      Input = ResponsesCreateRequestInput.CreateStr("Qual é a minha cor favorita?"),
      Tools = new List<ResponsesCreateRequestTool>
      {
          ResponsesCreateRequestTool.CreateHistoryToolDefinition(new HistoryToolDefinition()),
      },
      Store = true,
  });

  // O modelo chama a ferramenta de histórico, encontra a conversa anterior,
  // e responde: "Sua cor favorita é azul."
  ```

  ```python Python SDK theme={null}
  # Em uma nova sessão, o modelo pode recuperar conversas passadas
  result = sdk.llm.responses.create(
      model="meetkai:functionary-pt",
      input="Qual é a minha cor favorita?",
      tools=[{"type": "history"}],
      store=True,
  )

  # O modelo chama a ferramenta de histórico, encontra a conversa anterior,
  # e responde: "Sua cor favorita é azul."
  ```

  ```bash bash theme={null}
  curl https://apigw.mka1.com/api/v1/llm/responses \
    --request POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <mka1-api-key>' \
    --header 'X-On-Behalf-Of: <end-user-id>' \
    --data '{
      "model": "meetkai:functionary-pt",
      "input": "Qual é a minha cor favorita?",
      "tools": [{ "type": "history" }],
      "store": true
    }'
  ```
</CodeGroup>

## Exemplo completo: armazenar e recuperar entre sessões

Este exemplo mostra o fluxo completo — armazenando informações em uma solicitação e recuperando em outra.

<CodeGroup>
  ```bash CLI theme={null}
  # Sessão 1: Diga ao modelo algo para lembrar
  mka1 llm responses create \
    --model meetkai:functionary-pt \
    --body '{
      "input": "Lembre-se disto: o prazo do projeto é 15 de março e o orçamento é R$50.000.",
      "tools": [{ "type": "history" }],
      "store": true
    }'

  # Sessão 2: Pergunte sobre isso depois
  mka1 llm responses create \
    --model meetkai:functionary-pt \
    --body '{
      "input": "Qual é o prazo e o orçamento do projeto?",
      "tools": [{ "type": "history" }],
      "store": true
    }'
  ```

  ```ts MKA1 SDK theme={null}
  import { SDK } from '@meetkai/mka1';

  const mka1 = new SDK({
    bearerAuth: `Bearer ${YOUR_API_KEY}`,
  });

  const headers = { 'X-On-Behalf-Of': 'user-123' };

  // Sessão 1: Diga ao modelo algo para lembrar
  const first = await mka1.llm.responses.create({
    model: 'meetkai:functionary-pt',
    input: 'Lembre-se disto: o prazo do projeto é 15 de março e o orçamento é R$50.000.',
    tools: [{ type: 'history' }],
    store: true,
  }, { headers });

  console.log('Armazenado:', first.outputText);

  // Sessão 2: Pergunte sobre isso depois
  const second = await mka1.llm.responses.create({
    model: 'meetkai:functionary-pt',
    input: 'Qual é o prazo e o orçamento do projeto?',
    tools: [{ type: 'history' }],
    store: true,
  }, { headers });

  console.log('Recuperado:', second.outputText);
  // → "O prazo do projeto é 15 de março e o orçamento é R$50.000."
  ```

  ```ts OpenAI SDK theme={null}
  import OpenAI from 'openai';

  const openai = new OpenAI({
    apiKey: '<mka1-api-key>',
    baseURL: 'https://apigw.mka1.com/api/v1/llm/',
    defaultHeaders: { 'X-On-Behalf-Of': 'user-123' },
  });

  // Sessão 1: Diga ao modelo algo para lembrar
  const first = await openai.responses.create({
    model: 'meetkai:functionary-pt',
    input: 'Lembre-se disto: o prazo do projeto é 15 de março e o orçamento é R$50.000.',
    tools: [{ type: 'history' }],
    store: true,
    stream: false,
  });

  console.log('Armazenado:', first.output_text);

  // Sessão 2: Pergunte sobre isso depois
  const second = await openai.responses.create({
    model: 'meetkai:functionary-pt',
    input: 'Qual é o prazo e o orçamento do projeto?',
    tools: [{ type: 'history' }],
    store: true,
    stream: false,
  });

  console.log('Recuperado:', second.output_text);
  // → "O prazo do projeto é 15 de março e o orçamento é R$50.000."
  ```

  ```csharp C# SDK theme={null}
  using MeetKai.MKA1;
  using MeetKai.MKA1.Types.Components;

  var sdk = new SDK(
      bearerAuth: $"Bearer {YOUR_API_KEY}",
      serverUrl: "https://apigw.mka1.com"
  );

  var historyTools = new List<ResponsesCreateRequestTool>
  {
      ResponsesCreateRequestTool.CreateHistoryToolDefinition(new HistoryToolDefinition()),
  };

  // Sessão 1: Diga ao modelo algo para lembrar
  var first = await sdk.Llm.Responses.CreateAsync(new ResponsesCreateRequest()
  {
      Model = "meetkai:functionary-pt",
      Input = ResponsesCreateRequestInput.CreateStr(
          "Lembre-se disto: o prazo do projeto é 15 de março e o orçamento é R$50.000."),
      Tools = historyTools,
      Store = true,
  });

  Console.WriteLine($"Armazenado: {first.OutputText}");

  // Sessão 2: Pergunte sobre isso depois
  var second = await sdk.Llm.Responses.CreateAsync(new ResponsesCreateRequest()
  {
      Model = "meetkai:functionary-pt",
      Input = ResponsesCreateRequestInput.CreateStr(
          "Qual é o prazo e o orçamento do projeto?"),
      Tools = historyTools,
      Store = true,
  });

  Console.WriteLine($"Recuperado: {second.OutputText}");
  // -> "O prazo do projeto é 15 de março e o orçamento é R$50.000."
  ```

  ```python Python SDK theme={null}
  from mka1 import SDK

  sdk = SDK(bearer_auth="Bearer YOUR_API_KEY")

  # Sessão 1: Diga ao modelo algo para lembrar
  first = sdk.llm.responses.create(
      model="meetkai:functionary-pt",
      input="Lembre-se disto: o prazo do projeto é 15 de março e o orçamento é R$50.000.",
      tools=[{"type": "history"}],
      store=True,
  )

  print("Armazenado:", first.output_text)

  # Sessão 2: Pergunte sobre isso depois
  second = sdk.llm.responses.create(
      model="meetkai:functionary-pt",
      input="Qual é o prazo e o orçamento do projeto?",
      tools=[{"type": "history"}],
      store=True,
  )

  print("Recuperado:", second.output_text)
  # -> "O prazo do projeto é 15 de março e o orçamento é R$50.000."
  ```

  ```bash bash theme={null}
  # Sessão 1: Armazene informações
  curl https://apigw.mka1.com/api/v1/llm/responses \
    --request POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <mka1-api-key>' \
    --header 'X-On-Behalf-Of: user-123' \
    --data '{
      "model": "meetkai:functionary-pt",
      "input": "Lembre-se disto: o prazo do projeto é 15 de março e o orçamento é R$50.000.",
      "tools": [{ "type": "history" }],
      "store": true
    }'

  # Sessão 2: Recupere depois
  curl https://apigw.mka1.com/api/v1/llm/responses \
    --request POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <mka1-api-key>' \
    --header 'X-On-Behalf-Of: user-123' \
    --data '{
      "model": "meetkai:functionary-pt",
      "input": "Qual é o prazo e o orçamento do projeto?",
      "tools": [{ "type": "history" }],
      "store": true
    }'
  ```
</CodeGroup>

## Detalhes do comportamento

| Aspecto            | Detalhe                                                                                |
| ------------------ | -------------------------------------------------------------------------------------- |
| Armazenamento      | Automático — cada par de solicitação/resposta é indexado após a resposta ser concluída |
| Busca              | Semântica — usa embeddings vetoriais, não busca por palavras-chave                     |
| Escopo             | Por usuário final — isolado pelo cabeçalho `X-On-Behalf-Of`                            |
| Indexação          | Em segundo plano — não adiciona latência à resposta                                    |
| Resultados         | Até 10 interações passadas mais relevantes retornadas por busca                        |
| Tamanho da entrada | Texto truncado em 7.500 caracteres por entrada para embedding                          |

## Quando usar a ferramenta de histórico

* **Personalização**: Lembrar preferências do usuário, nomes ou contexto entre sessões
* **Continuidade de projetos**: Recuperar decisões, prazos ou requisitos discutidos anteriormente
* **Fluxos de suporte**: Manter contexto sobre o histórico de problemas de um usuário
* **Assistentes**: Criar assistentes que aprendem e se adaptam a cada usuário ao longo do tempo

## Próximos passos

* [Conversas](/pt/docs/conversations) — gerencie trocas de múltiplas mensagens em uma única sessão
* [Arquivos e vetores](/pt/docs/files-and-vector-stores) — armazene e busque documentos
* [Gerar uma resposta](/pt/docs/generate-a-response) — solicitações de texto e trocas multi-turno