ReferenciaSDKSDK de TypeScript

SDK

SDK de TypeScript

Usa los ayudantes de flujo de trabajo y la política de captura del SDK de TypeScript sin duplicar en la UI la semántica de memoria.

Instalación

Nota: El SDK programático de TypeScript (MemoryOSClient) aún no está publicado en npm. El paquete oficial @xmemo/client en npm es estrictamente el orquestador de CLI (configuración de cuenta, diagnósticos y el proxy local stdio xmemo-mcp). Hasta que se publique el SDK programático, integre las aplicaciones mediante la API REST (/docs/api/authentication) o el Model Context Protocol (/docs/mcp/overview). Instale el paquete oficial CLI @xmemo/client para la configuración de la cuenta, diagnósticos y administración local del servidor MCP:

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

Construir un cliente (Referencia de vista previa)

Referencia de vista previa: La siguiente construcción de cliente demuestra la próxima interfaz del SDK programático de TypeScript. Nota: MemoryOSClient aún no se distribuye en el paquete npm @xmemo/client publicado; las declaraciones de importación a continuación ilustran el uso futuro del SDK una vez lanzado. Mantenga la clave de API en el entorno; nunca la inserte en el código fuente ni en la configuración pública. Los valores opcionales agentId y agentInstanceId son campos de atribución, no credenciales.

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

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

Tipos de opciones de cliente (Referencia de vista previa)

Referencia de vista previa: Estos tipos de opciones representan la interfaz del próximo cliente del SDK. Los métodos de flujo de trabajo aceptan AgentWorkflowOptions, mientras que recallContext acepta 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 métodos reciben content: string y un objeto AgentWorkflowOptions opcional, y ambos devuelven Promise<CaptureResult>. taskStart proporciona por defecto status started y memoryType working; taskEnd proporciona completed y 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

Estos ayudantes de workflow usan exactamente la misma firma y tipo de retorno. recordDecision y recordBugFix establecen por defecto el tipo de memoria capturada en semantic; el tipo de evento identifica qué hecho del ciclo de vida se registró.

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' });

Forma de retorno de CaptureResult

taskStart, taskEnd, recordDecision, recordBugFix, recordCorrection, captureEvent y recordEvent resuelven todos a CaptureResult. La política puede devolver una decisión sin memory_id cuando omite un evento de baja señal; no supongas que cada llamada escribe.

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

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

Firma y solicitud de recallContext

recallContext envía una solicitud POST a /v1/recall/context y devuelve el objeto JSON del servidor. El SDK convierte opciones camelCase como maxItems y maxTokens a los campos REST max_items y max_tokens; los valores predeterminados son memory_type auto, status active, threshold 0.5 y 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,
});

Forma de retorno de recallContext

El tipo de retorno de TypeScript es intencionadamente Record<string, unknown> porque la respuesta REST puede incorporar campos aditivos. La forma base actual producida por el servidor es un objeto de contexto estructurado con los campos siguientes; items y los valores de presupuesto dependen de los datos.

{
  "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"
}

SDK recallContext frente a MCP recall_context

Usan la misma semántica acotada de recall-context y el mismo ensamblado de servidor subyacente, pero no son la misma superficie wire. El método del SDK es una llamada de cliente REST a /v1/recall/context autenticada con X-API-Key y devuelve JSON estructurado. La herramienta MCP la invoca un cliente MCP y genera una respuesta de texto pública que comienza con ### XMemo Context; usa el nombre de herramienta MCP con guion bajo solo en la superficie MCP.

  • Caller del SDK: código TypeScript que llama a client.recallContext(query, options).
  • Caller MCP: un cliente MCP que invoca recall_context con argumentos MCP.
  • Resultado del SDK: Record<string, unknown> con los campos base version, retrieval_plan, budget, items, context_text y answer_status.
  • Resultado MCP: texto público con líneas Reference, Type, Location y una sección Context; los detalles internos de recuperación no se exponen.

Secuencia de workflow

Un hook de producción puede recuperar el contexto existente, capturar eventos del ciclo de vida de la tarea y cerrarla. Cada ayudante de workflow sigue devolviendo CaptureResult, de modo que el caller puede inspeccionar shouldCapture, action, reason, qualityScore, event_id y el 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 });

Manejo de errores de autenticación

MemoryOSClient envía X-API-Key en sus solicitudes REST. Su método privado de solicitud lanza un Error simple para cada respuesta que no sea 2xx, con el prefijo exacto `Memory OS request failed: <status> ` seguido del cuerpo de respuesta. Gestiona 401 y 403 sin registrar la key ni contenido de respuesta que pueda contener datos sensibles. El MemoryOSHttpError exportado por separado pertenece a MemoryOSHttpClient, no a estos métodos de workflow 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 de la política de captura

captureEvent normaliza el evento, aplica la política determinista de captura y solo después escribe. Los eventos de baja señal devuelven shouldCapture: false sin escribir, mientras que el texto similar a un token se redacta antes de capturarlo. Inspecciona CaptureResult en lugar de suponer que un ayudante escribió una memoria.

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);
}

Fuente: Ayudantes de flujo del SDK