ReferenzSDKTypeScript-SDK

SDK

TypeScript-SDK

Nutzen Sie Workflow-Hilfsprogramme und Erfassungsrichtlinien aus dem TypeScript-SDK, ohne Speichersemantik in der Benutzeroberfläche zu duplizieren.

Installation

Hinweis: Das programmatische TypeScript SDK (MemoryOSClient) ist noch nicht auf npm veröffentlicht. Das offizielle @xmemo/client-Paket auf npm ist ausschließlich der CLI-Orchestrator (Kontoeinrichtung, Diagnose und der lokale xmemo-mcp stdio-Proxy). Bis zur Veröffentlichung des programmatischen SDKs sollten Anwendungen über die REST API (/docs/api/authentication) oder das Model Context Protocol (/docs/mcp/overview) integriert werden. Installieren Sie das offizielle @xmemo/client CLI-Paket für Kontoeinrichtung, Diagnose und lokale MCP-Server-Verwaltung:

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

Client erstellen (Vorschau-Referenz)

Vorschau-Referenz: Die folgende Client-Konstruktion zeigt die Schnittstelle des kommenden programmatischen TypeScript SDKs. Hinweis: MemoryOSClient ist noch nicht im veröffentlichten npm-Paket @xmemo/client enthalten; die folgenden Import-Anweisungen veranschaulichen die zukünftige Nutzung nach Veröffentlichung. Behalten Sie den API-Schlüssel in der Umgebung; binden Sie ihn niemals in den Quellcode oder die öffentliche Konfiguration ein. Optionale agentId- und agentInstanceId-Werte sind Zuordnungsfelder, keine Anmeldedaten.

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

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

Client-Optionstypen (Vorschau-Referenz)

Vorschau-Referenz: Diese Optionstypen stellen die Schnittstelle des kommenden SDK-Clients dar. Workflow-Methoden akzeptieren AgentWorkflowOptions, während recallContext RecallContextOptions akzeptiert.

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

Beide Methoden nehmen content: string und ein optionales AgentWorkflowOptions-Objekt entgegen und geben jeweils Promise<CaptureResult> zurück. taskStart liefert standardmäßig status started und memoryType working; taskEnd liefert completed und 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

Diese Workflow-Hilfsprogramme verwenden exakt dieselbe Signatur und denselben Rückgabetyp. recordDecision und recordBugFix setzen den erfassten Speichertyp standardmäßig auf semantic; der Ereignistyp identifiziert, welches Lebenszyklusereignis aufgezeichnet wurde.

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

Rückgabeform von CaptureResult

taskStart, taskEnd, recordDecision, recordBugFix, recordCorrection, captureEvent und recordEvent werden alle zu CaptureResult aufgelöst. Die Richtlinie kann eine Entscheidung ohne memory_id zurückgeben, wenn sie ein Ereignis mit geringer Signalwirkung überspringt; gehen Sie nicht davon aus, dass jeder Aufruf schreibt.

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

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

Signatur und Anfrage von recallContext

recallContext sendet eine POST-Anfrage an /v1/recall/context und gibt das JSON-Objekt des Servers zurück. Das SDK bildet camelCase-Optionen wie maxItems und maxTokens auf die REST-Felder max_items und max_tokens ab; die Standardwerte sind memory_type auto, status active, threshold 0.5 und 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,
});

Rückgabeform von recallContext

Der TypeScript-Rückgabetyp ist absichtlich Record<string, unknown>, da die REST-Antwort additive Felder hinzugewinnen kann. Die aktuelle vom Server erzeugte Kernstruktur ist ein strukturiertes Kontextobjekt mit den folgenden Feldern; items- und budget-Werte sind datenabhängig.

{
  "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 im Vergleich zu MCP recall_context

Sie nutzen dieselbe begrenzte recall-context-Semantik und denselben zugrundeliegenden Serveraufbau, sind jedoch nicht dieselbe Wire-Oberfläche. Die SDK-Methode ist ein REST-Client-Aufruf an /v1/recall/context, der mit X-API-Key authentifiziert wird und strukturiertes JSON zurückgibt. Das MCP-Tool wird von einem MCP-Client aufgerufen und rendert eine öffentliche Textantwort, die mit ### XMemo Context beginnt; verwenden Sie den MCP-Toolnamen mit Unterstrich ausschließlich auf der MCP-Oberfläche.

  • SDK-Aufrufer: TypeScript-Code, der client.recallContext(query, options) aufruft.
  • MCP-Aufrufer: Ein MCP-Client, der recall_context mit MCP-Argumenten aufruft.
  • SDK-Ergebnis: Record<string, unknown> mit den Kernfeldern version, retrieval_plan, budget, items, context_text und answer_status.
  • MCP-Ergebnis: Öffentlicher Text mit Reference-, Type- und Location-Zeilen sowie einem Context-Abschnitt; interne Abrufdetails werden nicht offengelegt.

Workflow-Ablauf

Ein Produktions-Hook kann vorhandenen Kontext abrufen, Aufgaben-Lebenszyklusereignisse erfassen und die Aufgabe abschließen. Jedes Workflow-Hilfsprogramm gibt weiterhin CaptureResult zurück, sodass der Aufrufer shouldCapture, action, reason, qualityScore, event_id und optionale memory_id prüfen kann.

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

Behandlung von Authentifizierungsfehlern

MemoryOSClient sendet X-API-Key bei seinen REST-Anfragen. Seine private request-Methode wirft bei jeder Nicht-2xx-Antwort einen einfachen Error mit dem exakten Präfix `Memory OS request failed: <status> `, gefolgt vom Antworttext. Behandeln Sie 401 und 403, ohne den Schlüssel oder Antwortinhalte zu protokollieren, die vertrauliche Daten enthalten könnten. Das separat exportierte MemoryOSHttpError gehört zu MemoryOSHttpClient, nicht zu diesen MemoryOSClient-Workflow-Methoden.

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

Ergebnis der Erfassungsrichtlinie

captureEvent normalisiert das Ereignis, wendet die deterministische Erfassungsrichtlinie an und schreibt erst dann. Ereignisse mit geringer Signalwirkung geben shouldCapture: false zurück, ohne zu schreiben, während token-ähnlicher Text vor der Erfassung unkenntlich gemacht wird. Überprüfen Sie das CaptureResult, anstatt davon auszugehen, dass ein Hilfsprogramm einen Speicher geschrieben hat.

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

Quelle: SDK-Workflow-Hilfsprogramme