Installation
Remarque : Le SDK TypeScript programmatique (MemoryOSClient) n'est pas encore publié sur npm. Le package officiel @xmemo/client sur npm est strictement l'orchestrateur CLI (configuration du compte, diagnostics et le proxy stdio local xmemo-mcp). En attendant la publication du SDK programmatique, intégrez les applications via l'API REST (/docs/api/authentication) ou le Model Context Protocol (/docs/mcp/overview). Installez le package CLI officiel @xmemo/client pour la configuration du compte, les diagnostics et la gestion locale du serveur MCP :
npm install -g @xmemo/client
npx @xmemo/client setup --url https://xmemo.devConstruire un client (Référence en avant-première)
Référence en avant-première : La construction de client suivante démontre l'interface du futur SDK TypeScript programmatique. Remarque : MemoryOSClient n'est pas encore distribué dans le package npm publié @xmemo/client ; les déclarations d'importation ci-dessous illustrent l'utilisation future du SDK une fois publié. Conservez la clé API dans l'environnement ; ne l'intégrez jamais dans le code source ou la configuration publique. Les valeurs facultatives agentId et agentInstanceId sont des champs d'attribution, pas des identifiants.
import { MemoryOSClient } from '@xmemo/client';
const client = new MemoryOSClient({
baseUrl: 'https://xmemo.dev',
apiKey: process.env.XMEMO_KEY!,
});Types d'options de client (Référence en avant-première)
Référence en avant-première : Ces types d'options représentent l'interface du futur client SDK. Les méthodes de flux de travail acceptent AgentWorkflowOptions, tandis que recallContext accepte 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
Les deux méthodes acceptent content: string et un objet facultatif AgentWorkflowOptions, et renvoient toutes deux Promise<CaptureResult>. taskStart fournit par défaut le statut started et le memoryType working ; taskEnd fournit completed et 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
Ces assistants de flux de travail utilisent exactement la même signature et le même type de retour. recordDecision et recordBugFix définissent par défaut le type de mémoire capturée sur semantic ; le type d'événement identifie quel fait du cycle de vie a été enregistré.
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' });Forme de retour de CaptureResult
taskStart, taskEnd, recordDecision, recordBugFix, recordCorrection, captureEvent et recordEvent renvoient tous CaptureResult. La politique peut renvoyer une décision sans memory_id lorsqu'elle ignore un événement de faible signal ; ne supposez pas que chaque appel écrit une mémoire.
interface CaptureResult extends CaptureDecision {
event_id: string;
memory_id?: string;
}
interface CaptureDecision {
shouldCapture: boolean;
reason: string;
action: CaptureAction;
qualityScore: number;
event: AgentEvent;
candidate?: MemoryCandidate;
}Signature et requête de recallContext
recallContext envoie une requête POST à /v1/recall/context et renvoie l'objet JSON du serveur. Le SDK mappe les options en camelCase telles que maxItems et maxTokens vers les champs REST max_items et max_tokens ; les valeurs par défaut sont memory_type auto, status active, threshold 0.5 et 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,
});Forme de retour de recallContext
Le type de retour TypeScript est intentionnellement Record<string, unknown> car la réponse REST peut s'enrichir de champs additifs. La structure principale actuelle générée par le serveur est un objet de contexte structuré avec les champs suivants ; les éléments et les valeurs budgétaires dépendent des données.
{
"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 versus MCP recall_context
Ils partagent la même sémantique de rappel de contexte délimité et le même assemblage serveur sous-jacent, mais ils ne constituent pas la même surface réseau. La méthode du SDK est un appel client REST vers /v1/recall/context authentifié par X-API-Key et renvoie du JSON structuré. L'outil MCP est appelé par un client MCP et génère une réponse textuelle publique commençant par ### XMemo Context ; utilisez le nom d'outil MCP avec un trait de soulignement uniquement sur la surface MCP.
- Appelant SDK : code TypeScript appelant client.recallContext(query, options).
- Appelant MCP : un client MCP appelant recall_context avec des arguments MCP.
- Résultat SDK : Record<string, unknown> avec les champs clés version, retrieval_plan, budget, items, context_text et answer_status.
- Résultat MCP : texte public avec des lignes Reference, Type, Location et une section Context ; les détails internes de récupération ne sont pas exposés.
Séquence de flux de travail
Un hook de production peut rappeler le contexte existant, capturer les événements de cycle de vie de la tâche et clôturer celle-ci. Chaque assistant de flux de travail renvoie toujours CaptureResult, permettant à l'appelant d'inspecter shouldCapture, action, reason, qualityScore, event_id et le memory_id facultatif.
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 });Gestion des erreurs d'authentification
MemoryOSClient transmet X-API-Key sur ses requêtes REST. Sa méthode privée de requête lève une Error standard sur chaque réponse non-2xx avec le préfixe exact `Memory OS request failed: <status> ` suivi du corps de réponse. Gérez 401 et 403 sans consigner la clé ni le contenu de réponse susceptible de contenir des données sensibles. La classe MemoryOSHttpError exportée séparément appartient à MemoryOSHttpClient, et non à ces méthodes de flux de travail 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');
}
}Résultat de la politique de capture
captureEvent normalise l'événement, applique la politique de capture déterministe et écrit seulement après coup. Les événements de faible signal renvoient shouldCapture: false sans écriture, tandis que le texte semblable à un jeton est caviardé avant la capture. Inspectez le CaptureResult plutôt que de présumer qu'un assistant a écrit une mémoire.
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);
}Source : Aides de flux de travail du SDK