@arkimedehq/recordare-client 0.3.0 → 0.4.0

package/README.md

@@ -38,6 +38,8 @@ await rc.ingestRoom({ conversation: { externalId: 'kitchen-1' }, recipients: ['u
   messages: [{ externalId: 'k1', speakerRef: 'c', content: 'Mi hanno preso in squadra!', sentAt: new Date().toISOString() }] });
 // Mode (only while the memory is empty, else MemoryNotEmptyError) and the first person's gender, from the profile.
 await rc.updateMe('user-42', { gender: 'feminine' });
+// The account is deleted: erase the whole memory (a key with the erase scope; the memory id confirms which).
+await rc.eraseMemory('user-42', (await rc.me('user-42')).memoryId);
 
 // Recall: one MCP session per user AND conversation (evidence of writes, the current turn), both bound in code.
 const tools = await rc.mcp.listTools('user-42', 'chat-1'); // build the agent's tools from these schemas
@@ -104,10 +106,9 @@ Everything else is here, the same for every client.
 deletions propagate, the name, mode and gender follow the platform, own content is marked, a source is learned in
 parts, listed and forgotten, recall over MCP carries the user and the conversation. Type checks there fail the build when this contract drifts from the service's schemas.
 
-## Synced copy (Arkimede)
-Arkimede still uses a copy of the sources instead of the npm package: `scripts/sync-to.sh <dir>` copies them into a
-host repository with a header naming the source commit (Arkimede: `backend/src/recordare/client/`). The host never
-edits them; change the library here and sync again. Switching to the npm package only changes the imports.
+## CommonJS hosts
+The package is ESM only. A CommonJS host (Arkimede's NestJS backend) loads it with `require`, which Node supports for
+ES modules from 20.19 / 22.12; with TypeScript, `"module": "nodenext"` (5.8 or later) type-checks that import.
 
 ## Development
 `npm ci`, `npm run typecheck`, `npm test`, `npm run build` (Node ≥ 20).

package/README_it.md

@@ -38,6 +38,8 @@ await rc.ingestRoom({ conversation: { externalId: 'kitchen-1' }, recipients: ['u
   messages: [{ externalId: 'k1', speakerRef: 'c', content: 'Mi hanno preso in squadra!', sentAt: new Date().toISOString() }] });
 // Modo (solo finché la memoria è vuota, altrimenti MemoryNotEmptyError) e genere della prima persona, dal profilo.
 await rc.updateMe('user-42', { gender: 'feminine' });
+// L'account viene eliminato: si cancella l'intera memoria (una chiave con lo scope erase; l'id della memoria conferma quale).
+await rc.eraseMemory('user-42', (await rc.me('user-42')).memoryId);
 
 // Richiamo: una sessione MCP per utente E conversazione (prove delle scritture, il turno corrente), entrambi fissati nel codice.
 const tools = await rc.mcp.listTools('user-42', 'chat-1'); // gli strumenti dell'agente nascono da questi schemi
@@ -108,11 +110,10 @@ volta sola, le cancellazioni si propagano, nome, modo e genere seguono la piatta
 fonte viene imparata a parti, elencata e dimenticata, il richiamo via MCP porta l'utente e la conversazione. I controlli di tipo lì fanno fallire la build se questo contratto si
 allontana dagli schemi del servizio.
 
-## Copia sincronizzata (Arkimede)
-Arkimede usa ancora una copia dei sorgenti invece del pacchetto npm: `scripts/sync-to.sh <dir>` copia i sorgenti nel
-repository dell'host con un'intestazione che indica il commit di origine (Arkimede: `backend/src/recordare/client/`).
-L'host non li modifica mai; si cambia la libreria qui e si sincronizza di nuovo. Passare al pacchetto npm cambia solo
-gli import.
+## Host CommonJS
+Il pacchetto è solo ESM. Un host CommonJS (il backend NestJS di Arkimede) lo carica con `require`, che Node supporta per
+i moduli ES dalla 20.19 / 22.12; con TypeScript, `"module": "nodenext"` (5.8 o successivo) controlla i tipi di
+quell'import.
 
 ## Sviluppo
 `npm ci`, `npm run typecheck`, `npm test`, `npm run build` (Node ≥ 20).

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { type Digest, type Episode, type EpisodeDetail, type EpisodeQuery, type ExportJob, type Fact, type FactDetail, type HolderIdentities, type IngestRequest, type IngestResult, type RoomRequest, type RoomResult, type LearnSource, type LinkCode, type LearnSourceResult, type Me, type MemorySettings, type MeSettings, type MemoryContext, type Note, type NoteChange, type NoteDetail, type PlanStatus, type Precision, type Source, type Usage } from './contract.js';
+import { type Cards, type ContextOptions, type Digest, type Episode, type Erased, type EpisodeDetail, type EpisodeQuery, type ExportJob, type Fact, type FactDetail, type HolderIdentities, type IngestRequest, type IngestResult, type RoomRequest, type RoomResult, type LearnSource, type LinkCode, type LearnSourceResult, type Me, type MemorySettings, type MeSettings, type MemoryContext, type Note, type NoteChange, type NoteDetail, type PlanStatus, type Precision, type Source, type Usage } from './contract.js';
 import { type ClientOptions, Http } from './http.js';
 import { RecordareMcp, type McpOptions } from './mcp.js';
 /**
@@ -16,6 +16,11 @@ export declare class RecordareClient {
     me(user: string): Promise<Me>;
     /** The memory's settings from the platform: the name (keep it in sync on every rename), the mode and the gender. */
     updateMe(user: string, settings: MeSettings): Promise<void>;
+    /**
+     * Erases the whole memory behind `user`, at once and for good (needs the `erase` scope): everything it holds goes.
+     * `memoryId` (from `me`) confirms which memory; a user without a memory answers 404, none is created.
+     */
+    eraseMemory(user: string, memoryId: string): Promise<Erased>;
     /** A one-time code for the holder to send from a channel (D51; personal memories only, else 409). */
     linkCode(user: string): Promise<LinkCode>;
     /** The identities that speak as the memory's "I" and the claims waiting for confirmation (D51). */
@@ -39,14 +44,14 @@ export declare class RecordareClient {
     /**
      * The memories relevant to `query` (the message about to be answered) as a fenced block to append to the prompt — or
      * null. Append it at the end of the system prompt (it changes every turn: keep the stable part first for prompt
-     * caching); never store it as a chat message.
+     * caching); never store it as a chat message. `card`: open it with the self card (who I am), off by default.
      */
-    context(user: string, conversation: string, query: string): Promise<MemoryContext>;
+    context(user: string, conversation: string, query: string, opts?: ContextOptions): Promise<MemoryContext>;
     /**
      * Stores the turn and returns the memory context for it in one round trip (needs the `ingest` and `read` scopes):
      * the context is computed for the ingested conversation, from `query` or else the turn's last user message.
      */
-    contextWithTurn(user: string, turn: IngestRequest, query?: string): Promise<MemoryContext>;
+    contextWithTurn(user: string, turn: IngestRequest, query?: string, opts?: ContextOptions): Promise<MemoryContext>;
     /** The conversation ended (session closed, /new): extraction runs now. A conversation Recordare never had is done. */
     endConversation(user: string, conversation: string): Promise<void>;
     /** An edited message: Recordare re-extracts what depended on it. */
@@ -102,6 +107,8 @@ export declare class RecordareClient {
         asOf?: string;
         includePending?: boolean;
     }): Promise<Fact[]>;
+    /** Who I am and who my contacts are: current facts and notes of the self and of each contact (no LLM). */
+    cards(user: string): Promise<Cards>;
     notes(user: string, query?: {
         category?: Note['category'];
         pinned?: boolean;

package/dist/client.js

@@ -41,6 +41,13 @@ export class RecordareClient {
             throw err;
         }
     }
+    /**
+     * Erases the whole memory behind `user`, at once and for good (needs the `erase` scope): everything it holds goes.
+     * `memoryId` (from `me`) confirms which memory; a user without a memory answers 404, none is created.
+     */
+    eraseMemory(user, memoryId) {
+        return this.http.request('DELETE', `api/v1/me${qs({ confirm: memoryId })}`, { user });
+    }
     /** A one-time code for the holder to send from a channel (D51; personal memories only, else 409). */
     linkCode(user) {
         return this.http.request('POST', 'api/v1/me/link-codes', { user });
@@ -113,17 +120,17 @@ export class RecordareClient {
     /**
      * The memories relevant to `query` (the message about to be answered) as a fenced block to append to the prompt — or
      * null. Append it at the end of the system prompt (it changes every turn: keep the stable part first for prompt
-     * caching); never store it as a chat message.
+     * caching); never store it as a chat message. `card`: open it with the self card (who I am), off by default.
      */
-    context(user, conversation, query) {
-        return this.http.request('POST', 'api/v1/context', { user, body: { query }, headers: { [CONVERSATION_HEADER]: conversation } });
+    context(user, conversation, query, opts = {}) {
+        return this.http.request('POST', 'api/v1/context', { user, body: { query, ...opts }, headers: { [CONVERSATION_HEADER]: conversation } });
     }
     /**
      * Stores the turn and returns the memory context for it in one round trip (needs the `ingest` and `read` scopes):
      * the context is computed for the ingested conversation, from `query` or else the turn's last user message.
      */
-    contextWithTurn(user, turn, query) {
-        return this.http.request('POST', 'api/v1/context', { user, body: { ingest: turn, ...(query ? { query } : {}) } });
+    contextWithTurn(user, turn, query, opts = {}) {
+        return this.http.request('POST', 'api/v1/context', { user, body: { ingest: turn, ...(query ? { query } : {}), ...opts } });
     }
     /** The conversation ended (session closed, /new): extraction runs now. A conversation Recordare never had is done. */
     async endConversation(user, conversation) {
@@ -193,6 +200,10 @@ export class RecordareClient {
     facts(user, query = {}) {
         return this.http.request('GET', `api/v1/facts${qs(query)}`, { user });
     }
+    /** Who I am and who my contacts are: current facts and notes of the self and of each contact (no LLM). */
+    cards(user) {
+        return this.http.request('GET', 'api/v1/cards', { user });
+    }
     notes(user, query = {}) {
         return this.http.request('GET', `api/v1/notes${qs(query)}`, { user });
     }

package/dist/contract.d.ts

@@ -29,6 +29,19 @@ export interface Me {
     via: string;
     scopes: string[];
 }
+/** `DELETE api/v1/me`: what erasing the whole memory took, by kind. */
+export interface Erased {
+    erased: {
+        conversations: number;
+        messages: number;
+        episodes: number;
+        facts: number;
+        notes: number;
+        digests: number;
+        sources: number;
+        contacts: number;
+    };
+}
 /** `PATCH api/v1/me`: the person's settings from their platform. */
 export interface MeSettings {
     /** Follows the platform's profile: send it again whenever the user renames themselves. */
@@ -392,6 +405,36 @@ export interface Source {
     episodeIds: string[];
 }
 /** `POST api/v1/context`: the memories relevant to the message a host is about to answer (WORK_PLAN 5.7). */
+/** `POST api/v1/context` options. */
+export interface ContextOptions {
+    /** Open the block with the self card — who I am: current facts and notes about me. Off by default. */
+    card?: boolean;
+}
+/** `GET api/v1/cards`: a person as the memory knows them now (WORK_PLAN 8.13). */
+export interface Card {
+    personId: string;
+    name: string;
+    aliases: string[];
+    facts: Array<{
+        id: string;
+        key: string;
+        value: string | null;
+        validFrom: string | null;
+    }>;
+    notes: Array<{
+        id: string;
+        category: string;
+        content: string;
+        pinned: boolean;
+        pattern: boolean;
+    }>;
+    /** The day of the latest episode about this contact (null for the self). */
+    lastMentioned: string | null;
+}
+export interface Cards {
+    self: Card;
+    contacts: Card[];
+}
 export interface MemoryContext {
     /** A fenced `<memory-context>` block to append to the prompt, or null (nothing relevant, or off). */
     block: string | null;

package/dist/mcp.js

@@ -80,7 +80,7 @@ export class RecordareMcp {
             },
             requestInit: { headers: { ...this.http.headers(user), [CONVERSATION_HEADER]: conversation } },
         });
-        const client = new Client(this.options.clientInfo ?? { name: 'recordare-client', version: '0.3.0' });
+        const client = new Client(this.options.clientInfo ?? { name: 'recordare-client', version: '0.4.0' });
         await client.connect(transport);
         return client;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkimedehq/recordare-client",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Client library for Recordare, the memory service for agent platforms: identity, ingest, deletions, MCP recall.",
   "license": "AGPL-3.0-or-later",
   "author": "Andrea Genovese",

package/src/client.ts

@@ -2,7 +2,7 @@
 // Copyright © 2026 Andrea Genovese
 
 import {
-  CONVERSATION_HEADER, type Digest, type Episode, type EpisodeDetail, type EpisodeQuery, type ExportJob, type Fact, type FactDetail,
+  type Cards, type ContextOptions, CONVERSATION_HEADER, type Digest, type Episode, type Erased, type EpisodeDetail, type EpisodeQuery, type ExportJob, type Fact, type FactDetail,
   type HolderIdentities, type IngestRequest, type IngestResult, type RoomRequest, type RoomResult, type LearnSource, type LinkCode, type LearnSourceResult, MAX_MESSAGES_PER_REQUEST, type Me, type MemorySettings,
   type MeSettings, type MemoryContext, type Note, type NoteChange, type NoteDetail, type PlanStatus, type Precision, type Source,
   SOURCE_PART_BYTES, type Usage,
@@ -50,6 +50,14 @@ export class RecordareClient {
     }
   }
 
+  /**
+   * Erases the whole memory behind `user`, at once and for good (needs the `erase` scope): everything it holds goes.
+   * `memoryId` (from `me`) confirms which memory; a user without a memory answers 404, none is created.
+   */
+  eraseMemory(user: string, memoryId: string): Promise<Erased> {
+    return this.http.request<Erased>('DELETE', `api/v1/me${qs({ confirm: memoryId })}`, { user });
+  }
+
   /** A one-time code for the holder to send from a channel (D51; personal memories only, else 409). */
   linkCode(user: string): Promise<LinkCode> {
     return this.http.request<LinkCode>('POST', 'api/v1/me/link-codes', { user });
@@ -128,18 +136,18 @@ export class RecordareClient {
   /**
    * The memories relevant to `query` (the message about to be answered) as a fenced block to append to the prompt — or
    * null. Append it at the end of the system prompt (it changes every turn: keep the stable part first for prompt
-   * caching); never store it as a chat message.
+   * caching); never store it as a chat message. `card`: open it with the self card (who I am), off by default.
    */
-  context(user: string, conversation: string, query: string): Promise<MemoryContext> {
-    return this.http.request<MemoryContext>('POST', 'api/v1/context', { user, body: { query }, headers: { [CONVERSATION_HEADER]: conversation } });
+  context(user: string, conversation: string, query: string, opts: ContextOptions = {}): Promise<MemoryContext> {
+    return this.http.request<MemoryContext>('POST', 'api/v1/context', { user, body: { query, ...opts }, headers: { [CONVERSATION_HEADER]: conversation } });
   }
 
   /**
    * Stores the turn and returns the memory context for it in one round trip (needs the `ingest` and `read` scopes):
    * the context is computed for the ingested conversation, from `query` or else the turn's last user message.
    */
-  contextWithTurn(user: string, turn: IngestRequest, query?: string): Promise<MemoryContext> {
-    return this.http.request<MemoryContext>('POST', 'api/v1/context', { user, body: { ingest: turn, ...(query ? { query } : {}) } });
+  contextWithTurn(user: string, turn: IngestRequest, query?: string, opts: ContextOptions = {}): Promise<MemoryContext> {
+    return this.http.request<MemoryContext>('POST', 'api/v1/context', { user, body: { ingest: turn, ...(query ? { query } : {}), ...opts } });
   }
 
   /** The conversation ended (session closed, /new): extraction runs now. A conversation Recordare never had is done. */
@@ -226,6 +234,11 @@ export class RecordareClient {
     return this.http.request('GET', `api/v1/facts${qs(query)}`, { user });
   }
 
+  /** Who I am and who my contacts are: current facts and notes of the self and of each contact (no LLM). */
+  cards(user: string): Promise<Cards> {
+    return this.http.request<Cards>('GET', 'api/v1/cards', { user });
+  }
+
   notes(user: string, query: { category?: Note['category']; pinned?: boolean; includePending?: boolean } = {}): Promise<Note[]> {
     return this.http.request('GET', `api/v1/notes${qs(query)}`, { user });
   }

package/src/contract.ts

@@ -37,6 +37,11 @@ export interface Me {
   scopes: string[];
 }
 
+/** `DELETE api/v1/me`: what erasing the whole memory took, by kind. */
+export interface Erased {
+  erased: { conversations: number; messages: number; episodes: number; facts: number; notes: number; digests: number; sources: number; contacts: number };
+}
+
 /** `PATCH api/v1/me`: the person's settings from their platform. */
 export interface MeSettings {
   /** Follows the platform's profile: send it again whenever the user renames themselves. */
@@ -335,6 +340,28 @@ export interface Source {
 }
 
 /** `POST api/v1/context`: the memories relevant to the message a host is about to answer (WORK_PLAN 5.7). */
+/** `POST api/v1/context` options. */
+export interface ContextOptions {
+  /** Open the block with the self card — who I am: current facts and notes about me. Off by default. */
+  card?: boolean;
+}
+
+/** `GET api/v1/cards`: a person as the memory knows them now (WORK_PLAN 8.13). */
+export interface Card {
+  personId: string;
+  name: string;
+  aliases: string[];
+  facts: Array<{ id: string; key: string; value: string | null; validFrom: string | null }>;
+  notes: Array<{ id: string; category: string; content: string; pinned: boolean; pattern: boolean }>;
+  /** The day of the latest episode about this contact (null for the self). */
+  lastMentioned: string | null;
+}
+
+export interface Cards {
+  self: Card;
+  contacts: Card[];
+}
+
 export interface MemoryContext {
   /** A fenced `<memory-context>` block to append to the prompt, or null (nothing relevant, or off). */
   block: string | null;

package/src/mcp.ts

@@ -99,7 +99,7 @@ export class RecordareMcp {
       },
       requestInit: { headers: { ...this.http.headers(user), [CONVERSATION_HEADER]: conversation } },
     });
-    const client = new Client(this.options.clientInfo ?? { name: 'recordare-client', version: '0.3.0' });
+    const client = new Client(this.options.clientInfo ?? { name: 'recordare-client', version: '0.4.0' });
     await client.connect(transport);
     return client;
   }