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:
npm install -g @xmemo/client
npx @xmemo/client setup --url https://xmemo.devConstruir 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.
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.
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.
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.
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.
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.
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.
{
"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.
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.
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.
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);
}Origem: Auxiliares de fluxo do SDK