# SDK TypeScript

Use os auxiliares de fluxo de trabalho e a política de captura do SDK TypeScript sem duplicar a semântica de memória na interface.

- Canonical: https://docs.xmemo.dev/pt-br/docs/sdk/typescript
- Locale: pt-BR
- Content-Locale: pt-BR
- Canonical-Content-Digest: 653aac1dcb59382f7266c99c91cd6e028767760475df9ae3b36a903b2283d333
- Edition-Digest: 95a229fa555b3f3dca882bec6e1591aaca16ea1978200b452bb4f63c5deddfb5
- Source-Revision: sha256:b831c81b583cfb5aec737b2369ccaa15a57a7f4f2f846d89d9f40fc118b9f4bb

## Instalação

Observação: O SDK programático do TypeScript (MemoryOSClient) ainda não foi publicado no npm. O pacote oficial @xmemo/client no npm é estritamente o orquestrador da CLI (configuração de conta, diagnósticos e o proxy stdio local xmemo-mcp). Até que o SDK programático seja lançado, integre aplicativos por meio da API REST (/docs/api/authentication) ou do Model Context Protocol (/docs/mcp/overview).

Instale o pacote CLI oficial @xmemo/client para configuração de conta, diagnósticos e gerenciamento local do servidor MCP:

```bash
npm install -g @xmemo/client
npx @xmemo/client setup --url https://xmemo.dev
```

## Construir um cliente (Referência de prévia)

Referência de prévia: A construção de cliente a seguir demonstra a futura interface do SDK programático em TypeScript. Observação: MemoryOSClient ainda não é distribuído no pacote npm @xmemo/client publicado; as declarações de importação abaixo ilustram o uso futuro do SDK após seu lançamento. Mantenha a chave da API no ambiente; nunca a inclua diretamente no código-fonte ou em uma configuração pública. Os valores opcionais agentId e agentInstanceId são campos de atribuição, não credenciais.

```ts
import { MemoryOSClient } from '@xmemo/client';

const client = new MemoryOSClient({
  baseUrl: 'https://xmemo.dev',
  apiKey: process.env.XMEMO_KEY!,
});
```

## Tipos de opção de cliente (Referência de prévia)

Referência de prévia: Esses tipos de opção representam a futura interface de cliente do SDK. Os métodos de fluxo aceitam AgentWorkflowOptions, enquanto recallContext aceita RecallContextOptions.

```ts
interface MemoryOSClientOptions {
  baseUrl: string;
  apiKey: string;
  fetchImpl?: typeof fetch;
  agentId?: string;
  agentInstanceId?: string;
}

interface AgentWorkflowOptions extends CaptureOptions {
  agentId?: string;
  agentInstanceId?: string;
  sessionId?: string;
  taskId?: string;
  status?: string;
  metadata?: Record<string, unknown>;
  memoryType?: MemoryType;
}

interface RecallContextOptions extends RecallPlanOptions {
  status?: string;
  threshold?: number;
  maxItems?: number;
  maxTokens?: number;
  limit?: number;
}
```

## taskStart / taskEnd

Ambos os métodos recebem content: string e um objeto AgentWorkflowOptions opcional, e ambos retornam Promise<CaptureResult>. taskStart fornece por padrão status started e memoryType working; taskEnd fornece completed e working.

```ts
async taskStart(content: string, options: AgentWorkflowOptions = {}): Promise<CaptureResult>
async taskEnd(content: string, options: AgentWorkflowOptions = {}): Promise<CaptureResult>

await client.taskStart('Implement MCP token repair', { source: 'codex', sessionId: 's1', taskId: 'p0' });
await client.taskEnd('MCP token repair completed', { source: 'codex', sessionId: 's1', taskId: 'p0' });
```

## recordDecision / recordBugFix

Esses auxiliares de fluxo usam a mesma assinatura e o mesmo tipo de retorno. recordDecision e recordBugFix definem por padrão o tipo de memória capturada como semantic; o tipo de evento identifica qual fato do ciclo de vida foi registrado.

```ts
async recordDecision(content: string, options: AgentWorkflowOptions = {}): Promise<CaptureResult>
async recordBugFix(content: string, options: AgentWorkflowOptions = {}): Promise<CaptureResult>

await client.recordDecision('Remote agents should use network MCP, not SSH stdio', { source: 'codex', scope: 'memory-os' });
await client.recordBugFix('Fixed streamable-http token identity fallback', { source: 'codex', taskId: 'p0' });
```

## Formato de retorno de CaptureResult

taskStart, taskEnd, recordDecision, recordBugFix, recordCorrection, captureEvent e recordEvent resolvem todos para CaptureResult. A política pode retornar uma decisão sem memory_id quando ignora um evento de baixo sinal; não presuma que toda chamada grava algo.

```ts
interface CaptureResult extends CaptureDecision {
  event_id: string;
  memory_id?: string;
}

interface CaptureDecision {
  shouldCapture: boolean;
  reason: string;
  action: CaptureAction;
  qualityScore: number;
  event: AgentEvent;
  candidate?: MemoryCandidate;
}
```

## Assinatura e solicitação de recallContext

recallContext envia uma solicitação POST para /v1/recall/context e retorna o objeto JSON do servidor. O SDK converte opções camelCase como maxItems e maxTokens nos campos REST max_items e max_tokens; os padrões são memory_type auto, status active, threshold 0.5 e prefer_working true.

```ts
async recallContext(query: string, options: RecallContextOptions = {}): Promise<Record<string, unknown>>

const context = await client.recallContext('current task and recent decisions', {
  scope: 'memory-os',
  maxItems: 6,
  maxTokens: 1200,
  preferWorking: true,
});
```

## Formato de retorno de recallContext

O tipo de retorno TypeScript é intencionalmente Record<string, unknown>, pois a resposta REST pode ganhar campos aditivos. O formato principal produzido atualmente pelo servidor é um objeto de contexto estruturado com os campos a seguir; os valores de items e orçamento dependem dos dados.

```json
{
  "version": "value-density-v2",
  "query": "current task and recent decisions",
  "retrieval_plan": {
    "query": "...",
    "selected_memory_types": ["working", "semantic"]
  },
  "budget": {
    "max_items": 6,
    "max_tokens": 1200,
    "used_items": <number>,
    "used_tokens": <number>,
    "skipped_items": <number>,
    "filtered_items": <number>,
    "structured_skipped_items": <number>,
    "budget_skipped_items": <number>,
    "truncated_items": <number>,
    "candidate_items": <number>,
    "selection_strategy": "top-primary-plus-stable-value-density",
    "budget_tradeoff": <boolean>,
    "token_scope": "context_text"
  },
  "items": [<structured context item>],
  "context_text": "<assembled context>",
  "answer_status": "primary_answer_available"
}
```

## recallContext do SDK versus recall_context do MCP

Eles usam a mesma semântica limitada de recall-context e a mesma montagem subjacente no servidor, mas não são a mesma superfície de rede. O método do SDK é uma chamada REST para /v1/recall/context autenticada com X-API-Key e retorna JSON estruturado. A ferramenta MCP é chamada por um cliente MCP e renderiza uma resposta pública em texto que começa com ### XMemo Context; use o nome da ferramenta MCP com sublinhado apenas na superfície MCP.

- Chamador do SDK: código TypeScript chamando client.recallContext(query, options).
- Chamador do MCP: um cliente MCP invocando recall_context com argumentos MCP.
- Resultado do SDK: Record<string, unknown> com os campos principais version, retrieval_plan, budget, items, context_text e answer_status.
- Resultado do MCP: texto público com linhas Reference, Type e Location e uma seção Context; os detalhes internos da recuperação não são expostos.

## Sequência do fluxo de trabalho

Um hook de produção pode recuperar o contexto existente, capturar eventos do ciclo de vida da tarefa e encerrá-la. Todo auxiliar de fluxo continua retornando CaptureResult, permitindo inspecionar shouldCapture, action, reason, qualityScore, event_id e o memory_id opcional.

```ts
const scope = 'memory-os';
const sessionId = crypto.randomUUID();

await client.recallContext('current task and recent decisions', { scope, preferWorking: true });
await client.taskStart('Implement production adapter hook', { source: 'codex', sessionId, scope });
await client.recordDecision('Use the hosted MCP transport', { source: 'codex', sessionId, scope });
await client.taskEnd('Production adapter hook implemented', { source: 'codex', sessionId, scope });
```

## Tratamento de erros de autenticação

MemoryOSClient envia X-API-Key nas solicitações REST. Seu método privado de solicitação lança um Error simples em toda resposta que não seja 2xx, com o prefixo exato `Memory OS request failed: <status> ` seguido pelo corpo da resposta. Trate 401 e 403 sem registrar a chave nem o conteúdo da resposta, que pode conter dados sensíveis. O MemoryOSHttpError exportado separadamente pertence a MemoryOSHttpClient, não a esses métodos de fluxo de MemoryOSClient.

```ts
try {
  await client.recallContext('connection check', { maxItems: 1 });
} catch (error) {
  if (error instanceof Error) {
    // The message starts: Memory OS request failed: <status> <response body>
    console.error('XMemo request failed; re-check XMEMO_KEY and required scope');
  }
}
```

## Resultado da política de captura

captureEvent normaliza o evento, aplica a política determinística de captura e só então grava. Eventos de baixo sinal retornam shouldCapture: false sem gravar, enquanto textos semelhantes a tokens são mascarados antes da captura. Inspecione o CaptureResult em vez de presumir que um auxiliar gravou uma memória.

```ts
const result = await client.recordDecision('Remote agents should use network MCP, not SSH stdio', { source: 'codex' });
if (result.shouldCapture) {
  console.log(result.event_id, result.memory_id);
} else {
  console.log(result.reason, result.action);
}
```