@arkimedehq/recordare-client 0.2.0 → 0.4.0

package/README.md

@@ -19,9 +19,9 @@ import { PersonDirectory, RecordareClient, afterFailure } from '@arkimedehq/reco
 const rc = new RecordareClient({ baseUrl: 'http://recordare:8080', apiKey: process.env.RECORDARE_API_KEY!,
   headers: () => traceHeaders() });                       // e.g. OpenTelemetry propagation.inject
 
-// Which memory the user's account opens, its mode (personal | entity) and Atlas address; the name follows the platform's profile. `enabled` is the
+// Which memory the user's account opens, its mode (personal | entity) and Atlas address; the name and gender follow the platform's profile. `enabled` is the
 // platform's own memory switch: while false, Recordare is not contacted (no consent flag in Recordare, D50).
-const people = new PersonDirectory(rc, { user: async (id) => ({ enabled: true, name: 'Andrea' }) });
+const people = new PersonDirectory(rc, { user: async (id) => ({ enabled: true, name: 'Andrea', gender: 'masculine' }) });
 const person = await people.refresh('user-42');           // { memoryId, mode, atlasUrl }; peek() reads the cache
 
 // Ingest (split into requests of 500, idempotent on each externalId): → { conversationId, accepted, duplicates, conflicts }.
@@ -32,8 +32,14 @@ await rc.ingest('user-42', { conversation: { externalId: 'chat-1' }, messages: [
 await rc.ingest('user-42', { conversation: { externalId: 'doc-1', source: 'document' }, messages: [
   { externalId: 'd1', role: 'user', own: true, content: 'La caldaia va revisionata ogni due anni.', sentAt: new Date().toISOString() },
 ] });
+// A room transcript (continuous listening): Recordare fans it out to the memories of the people present.
+await rc.ingestRoom({ conversation: { externalId: 'kitchen-1' }, recipients: ['user-42', 'user-7'],
+  speakers: [{ ref: 'a', user: 'user-42' }, { ref: 'b', user: 'user-7' }, { ref: 'c', displayName: 'Leo', identity: { channel: 'voice', externalId: 'leo' } }],
+  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
@@ -68,7 +74,28 @@ await rc.learnSource('user-42', { externalId: 'boiler-manual', title: 'Manuale d
 
 ## The diary
 `episodes`, `episode`, `digests`, `facts`, `notes`, `plans` read what Recordare remembers for the person's own view in
-the platform's UI; `correctEpisode`, `forgetEpisode`, `pinNote`, `delete`, `decide` are the person's edits (API.md §4).
+the platform's UI; `correctEpisode`, `forgetEpisode`, `forgetPeriod`, `pinNote`, `delete`, `decide` are the person's edits (API.md §4).
+`fact`, `note` give one item with its evidence; `addEpisode`, `addNote` are written by the person (stated, theirs);
+`correctFact`, `correctNote` keep the wrong version as history. `noteChanges` is the change feed for a platform keeping a
+copy of the notes (pass `next` back as `since`). `settings`, `usage` read the memory's settings and the LLM calls spent on
+it; `updateSettings` and the export (`startExport` → `exportJob` → `exportArchive`) need the memory's personal token
+(scopes `memory_settings`, `export`; pass `user` empty).
+
+## Linking the holder's channel identity (D51)
+In a personal memory a channel sender speaks as "I" only once the holder links it: `linkCode(user)` → `{code,
+expiresAt}` (`RCD-XXXX-XXXX`, ten minutes, one use) — the holder sends the code alone to the agent from that channel, in
+a direct chat (set `conversation.direct` on the ingest when you know it; `false` = a group, where a code claims nothing);
+then `holderIdentities(user)` → `{linked, pending}`, and `confirmHolderClaim(user, id)` / `rejectHolderClaim(user, id)`
+within seven days; `unlinkHolderIdentity(user, id)` undoes a link. Recordare never stores the code's message, but your
+model sees it: when `isLinkCode(text)` (the service's own `LINK_CODE` pattern), send the turn at once and give the model
+`LINK_CODE_INSTRUCTION` instead of a memory context.
+
+```ts
+const { code } = await rc.linkCode('user-42');            // show it to the holder
+if (isLinkCode(text)) systemExtra = LINK_CODE_INSTRUCTION; // the model says the code was received, without repeating it
+const { pending } = await rc.holderIdentities('user-42');
+await rc.confirmHolderClaim('user-42', pending[0].id);
+```
 
 ## What stays with the host
 How it stores its outbox (its own database, its own transaction) and how it maps its chats to the ingest contract.
@@ -79,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

@@ -19,9 +19,9 @@ import { PersonDirectory, RecordareClient, afterFailure } from '@arkimedehq/reco
 const rc = new RecordareClient({ baseUrl: 'http://recordare:8080', apiKey: process.env.RECORDARE_API_KEY!,
   headers: () => traceHeaders() });                       // es. propagation.inject di OpenTelemetry
 
-// Quale memoria apre l'account dell'utente, il suo modo (personal | entity) e l'indirizzo di Atlas; il nome segue il profilo sulla piattaforma. `enabled` è
+// Quale memoria apre l'account dell'utente, il suo modo (personal | entity) e l'indirizzo di Atlas; il nome e il genere seguono il profilo sulla piattaforma. `enabled` è
 // l'interruttore della memoria della piattaforma: finché è false Recordare non viene contattato (niente consenso, D50).
-const people = new PersonDirectory(rc, { user: async (id) => ({ enabled: true, name: 'Andrea' }) });
+const people = new PersonDirectory(rc, { user: async (id) => ({ enabled: true, name: 'Andrea', gender: 'masculine' }) });
 const person = await people.refresh('user-42');           // { memoryId, mode, atlasUrl }; peek() legge la cache
 
 // Ingest (diviso in richieste da 500, idempotente su ogni externalId): → { conversationId, accepted, duplicates, conflicts }.
@@ -32,8 +32,14 @@ await rc.ingest('user-42', { conversation: { externalId: 'chat-1' }, messages: [
 await rc.ingest('user-42', { conversation: { externalId: 'doc-1', source: 'document' }, messages: [
   { externalId: 'd1', role: 'user', own: true, content: 'La caldaia va revisionata ogni due anni.', sentAt: new Date().toISOString() },
 ] });
+// Una trascrizione di stanza (ascolto continuo): Recordare la distribuisce alle memorie delle persone presenti.
+await rc.ingestRoom({ conversation: { externalId: 'kitchen-1' }, recipients: ['user-42', 'user-7'],
+  speakers: [{ ref: 'a', user: 'user-42' }, { ref: 'b', user: 'user-7' }, { ref: 'c', displayName: 'Leo', identity: { channel: 'voice', externalId: 'leo' } }],
+  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
@@ -69,8 +75,30 @@ await rc.learnSource('user-42', { externalId: 'boiler-manual', title: 'Manuale d
 
 ## Il diario
 `episodes`, `episode`, `digests`, `facts`, `notes`, `plans` leggono ciò che Recordare ricorda, per la vista della persona
-nell'interfaccia della piattaforma; `correctEpisode`, `forgetEpisode`, `pinNote`, `delete`, `decide` sono le modifiche
-della persona (API.md §4).
+nell'interfaccia della piattaforma; `correctEpisode`, `forgetEpisode`, `forgetPeriod`, `pinNote`, `delete`, `decide` sono le modifiche
+della persona (API.md §4). `fact`, `note` danno un elemento con le sue prove; `addEpisode`, `addNote` sono scritti dalla
+persona (dichiarati, suoi); `correctFact`, `correctNote` tengono la versione sbagliata come cronologia. `noteChanges` è il
+feed delle modifiche per una piattaforma che tiene una copia delle note (si ripassa `next` come `since`). `settings`,
+`usage` leggono le impostazioni della memoria e le chiamate LLM spese per essa; `updateSettings` e l'export
+(`startExport` → `exportJob` → `exportArchive`) richiedono il token personale della memoria (scope `memory_settings`,
+`export`; `user` vuoto).
+
+## Collegare l'identità di canale del titolare (D51)
+In una memoria personale un mittente di un canale parla come "io" solo dopo che il titolare l'ha collegato:
+`linkCode(user)` → `{code, expiresAt}` (`RCD-XXXX-XXXX`, dieci minuti, un solo uso) — il titolare invia il codice da
+solo all'agente da quel canale, in una chat diretta (impostare `conversation.direct` nell'ingest quando lo si sa;
+`false` = un gruppo, dove un codice non chiede nulla); poi `holderIdentities(user)` → `{linked, pending}`, e
+`confirmHolderClaim(user, id)` / `rejectHolderClaim(user, id)` entro sette giorni; `unlinkHolderIdentity(user, id)`
+annulla un collegamento. Recordare non salva mai il messaggio del codice, ma il modello lo vede: quando `isLinkCode(text)`
+(lo stesso pattern `LINK_CODE` del servizio), inviare subito il turno e dare al modello `LINK_CODE_INSTRUCTION` al posto
+del contesto di memoria.
+
+```ts
+const { code } = await rc.linkCode('user-42');            // da mostrare al titolare
+if (isLinkCode(text)) systemExtra = LINK_CODE_INSTRUCTION; // il modello dice che il codice è arrivato, senza ripeterlo
+const { pending } = await rc.holderIdentities('user-42');
+await rc.confirmHolderClaim('user-42', pending[0].id);
+```
 
 ## Cosa resta all'host
 Come conserva la sua outbox (il suo database, la sua transazione) e come trasforma le sue chat nel contratto di
@@ -82,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 Fact, type IngestRequest, type IngestResult, type LearnSource, type LearnSourceResult, type Me, type MeSettings, type MemoryContext, type Note, type PlanStatus, type Precision, type Source } 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,22 +16,42 @@ 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). */
+    holderIdentities(user: string): Promise<HolderIdentities>;
+    /** Confirms a claim: that channel identity is the holder from now on. */
+    confirmHolderClaim(user: string, id: string): Promise<void>;
+    /** Rejects a claim (not the holder). */
+    rejectHolderClaim(user: string, id: string): Promise<void>;
+    /** Unlinks one of the holder's identities. */
+    unlinkHolderIdentity(user: string, id: string): Promise<void>;
     /**
      * Sends messages of one conversation, split into requests of at most MAX_MESSAGES_PER_REQUEST. Idempotent: Recordare
      * deduplicates on each message's externalId. Recordare always stores (D50): the on/off switch is the platform's.
      */
     ingest(user: string, req: IngestRequest): Promise<IngestResult>;
+    /**
+     * Sends a room transcript to the memories of the people present (continuous listening), split into requests of at
+     * most MAX_MESSAGES_PER_REQUEST; needs a client key (not a personal token). Idempotent like `ingest`.
+     */
+    ingestRoom(req: RoomRequest): Promise<RoomResult>;
     /**
      * 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. */
@@ -63,6 +83,20 @@ export declare class RecordareClient {
     }): Promise<string>;
     /** The person forgets an episode: it is removed and never recreated. */
     forgetEpisode(user: string, id: string): Promise<void>;
+    /**
+     * The person forgets a period (days or months, inclusive): its episodes and raw messages (`keepRaw`: kept but hidden
+     * and never extracted again), with what only they supported. Returns how much went.
+     */
+    forgetPeriod(user: string, period: {
+        from: string;
+        to: string;
+        keepRaw?: boolean;
+    }): Promise<{
+        episodes: number;
+        messages: number;
+        facts: number;
+        notes: number;
+    }>;
     digests(user: string, query?: {
         level?: 'day' | 'month';
         from?: string;
@@ -73,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;
@@ -87,6 +123,60 @@ export declare class RecordareClient {
     delete(user: string, what: 'notes' | 'facts', id: string): Promise<void>;
     /** A pending (inferred) note or fact: confirmed it becomes the person's, rejected it is removed. */
     decide(user: string, what: 'notes' | 'facts', id: string, decision: 'confirm' | 'reject'): Promise<void>;
+    /** The person writes an episode in the platform's UI (stated, theirs). Returns its id. */
+    addEpisode(user: string, episode: {
+        content: string;
+        kind?: 'event' | 'plan';
+        occurredAt?: string;
+        occurredUntil?: string;
+        datePrecision?: Exclude<Precision, 'unknown' | 'minute'>;
+        place?: string;
+        people?: string[];
+    }): Promise<string>;
+    /** The person writes a note in the platform's UI (stated, theirs). Returns its id. */
+    addNote(user: string, note: {
+        content: string;
+        category?: Note['category'];
+    }): Promise<string>;
+    fact(user: string, id: string): Promise<FactDetail>;
+    note(user: string, id: string): Promise<NoteDetail>;
+    /** The person corrects a current fact (`value` null: not known any more); the wrong one stays in its history. */
+    correctFact(user: string, id: string, fix: {
+        value: string | null;
+        validFrom?: string;
+        datePrecision?: Exclude<Precision, 'unknown' | 'minute'>;
+    }): Promise<string>;
+    /** The person corrects a current note; the wrong one stays as `corrected`. */
+    correctNote(user: string, id: string, fix: {
+        content: string;
+        category?: Note['category'];
+    }): Promise<string>;
+    /** The notes change feed, for a platform keeping a copy: pass `next` back as `since`; `more` when the page was full. */
+    noteChanges(user: string, query?: {
+        since?: number;
+        limit?: number;
+    }): Promise<{
+        items: NoteChange[];
+        next: number;
+        more: boolean;
+    }>;
+    settings(user: string): Promise<MemorySettings>;
+    /** Needs `memory_settings`: the memory's personal token (never a client key); pass `user` empty with it. */
+    updateSettings(user: string, patch: {
+        locale?: string;
+        timezone?: string;
+        qualityProfile?: MemorySettings['qualityProfile'];
+    }): Promise<MemorySettings>;
+    /** LLM calls and tokens spent on the memory between two local days (default: the last 30). */
+    usage(user: string, query?: {
+        from?: string;
+        to?: string;
+    }): Promise<Usage>;
+    /** Starts a full export (needs `export`: the memory's personal token); poll `exportJob`, then `exportArchive`. */
+    startExport(user: string): Promise<ExportJob>;
+    exportJob(user: string, id: string): Promise<ExportJob>;
+    /** The finished export: one JSON archive (`format: "recordare-export/1"`). */
+    exportArchive(user: string, id: string): Promise<Record<string, unknown>>;
     /** Closes the MCP sessions (on shutdown). */
     close(): Promise<void>;
     private gone;

package/dist/client.js

@@ -41,6 +41,33 @@ 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 });
+    }
+    /** The identities that speak as the memory's "I" and the claims waiting for confirmation (D51). */
+    holderIdentities(user) {
+        return this.http.request('GET', 'api/v1/me/identities', { user });
+    }
+    /** Confirms a claim: that channel identity is the holder from now on. */
+    async confirmHolderClaim(user, id) {
+        await this.http.request('POST', `api/v1/me/identities/pending/${encodeURIComponent(id)}/confirm`, { user });
+    }
+    /** Rejects a claim (not the holder). */
+    async rejectHolderClaim(user, id) {
+        await this.http.request('DELETE', `api/v1/me/identities/pending/${encodeURIComponent(id)}`, { user });
+    }
+    /** Unlinks one of the holder's identities. */
+    async unlinkHolderIdentity(user, id) {
+        await this.http.request('DELETE', `api/v1/me/identities/${encodeURIComponent(id)}`, { user });
+    }
     /**
      * Sends messages of one conversation, split into requests of at most MAX_MESSAGES_PER_REQUEST. Idempotent: Recordare
      * deduplicates on each message's externalId. Recordare always stores (D50): the on/off switch is the platform's.
@@ -65,20 +92,45 @@ export class RecordareClient {
         }
         return total;
     }
+    /**
+     * Sends a room transcript to the memories of the people present (continuous listening), split into requests of at
+     * most MAX_MESSAGES_PER_REQUEST; needs a client key (not a personal token). Idempotent like `ingest`.
+     */
+    async ingestRoom(req) {
+        const total = new Map();
+        for (let i = 0; i < req.messages.length; i += MAX_MESSAGES_PER_REQUEST) {
+            const last = i + MAX_MESSAGES_PER_REQUEST >= req.messages.length;
+            const part = await this.http.request('POST', 'api/v1/ingest/room', {
+                body: { ...req, messages: req.messages.slice(i, i + MAX_MESSAGES_PER_REQUEST), hints: req.hints && last ? req.hints : undefined },
+            });
+            for (const r of part.recipients) {
+                const t = total.get(r.user);
+                if (!t)
+                    total.set(r.user, { ...r, conflicts: [...r.conflicts] });
+                else {
+                    t.conversationId = r.conversationId ?? t.conversationId;
+                    t.accepted += r.accepted;
+                    t.duplicates += r.duplicates;
+                    t.conflicts.push(...r.conflicts);
+                }
+            }
+        }
+        return { recipients: [...total.values()] };
+    }
     /**
      * 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) {
@@ -135,12 +187,23 @@ export class RecordareClient {
     async forgetEpisode(user, id) {
         await this.http.request('DELETE', `api/v1/episodes/${enc(id)}`, { user });
     }
+    /**
+     * The person forgets a period (days or months, inclusive): its episodes and raw messages (`keepRaw`: kept but hidden
+     * and never extracted again), with what only they supported. Returns how much went.
+     */
+    forgetPeriod(user, period) {
+        return this.http.request('POST', 'api/v1/forget', { user, body: period });
+    }
     digests(user, query = {}) {
         return this.http.request('GET', `api/v1/digests${qs(query)}`, { user });
     }
     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 });
     }
@@ -159,6 +222,54 @@ export class RecordareClient {
     async decide(user, what, id, decision) {
         await this.http.request('POST', `api/v1/${what}/${enc(id)}/${decision}`, { user });
     }
+    /** The person writes an episode in the platform's UI (stated, theirs). Returns its id. */
+    async addEpisode(user, episode) {
+        return (await this.http.request('POST', 'api/v1/episodes', { user, body: episode })).id;
+    }
+    /** The person writes a note in the platform's UI (stated, theirs). Returns its id. */
+    async addNote(user, note) {
+        return (await this.http.request('POST', 'api/v1/notes', { user, body: note })).id;
+    }
+    fact(user, id) {
+        return this.http.request('GET', `api/v1/facts/${enc(id)}`, { user });
+    }
+    note(user, id) {
+        return this.http.request('GET', `api/v1/notes/${enc(id)}`, { user });
+    }
+    /** The person corrects a current fact (`value` null: not known any more); the wrong one stays in its history. */
+    async correctFact(user, id, fix) {
+        return (await this.http.request('POST', `api/v1/facts/${enc(id)}/corrections`, { user, body: fix })).id;
+    }
+    /** The person corrects a current note; the wrong one stays as `corrected`. */
+    async correctNote(user, id, fix) {
+        return (await this.http.request('POST', `api/v1/notes/${enc(id)}/corrections`, { user, body: fix })).id;
+    }
+    /** The notes change feed, for a platform keeping a copy: pass `next` back as `since`; `more` when the page was full. */
+    noteChanges(user, query = {}) {
+        return this.http.request('GET', `api/v1/notes/changes${qs(query)}`, { user });
+    }
+    settings(user) {
+        return this.http.request('GET', 'api/v1/settings', { user });
+    }
+    /** Needs `memory_settings`: the memory's personal token (never a client key); pass `user` empty with it. */
+    updateSettings(user, patch) {
+        return this.http.request('PATCH', 'api/v1/settings', { user, body: patch });
+    }
+    /** LLM calls and tokens spent on the memory between two local days (default: the last 30). */
+    usage(user, query = {}) {
+        return this.http.request('GET', `api/v1/usage${qs(query)}`, { user });
+    }
+    /** Starts a full export (needs `export`: the memory's personal token); poll `exportJob`, then `exportArchive`. */
+    startExport(user) {
+        return this.http.request('POST', 'api/v1/exports', { user });
+    }
+    exportJob(user, id) {
+        return this.http.request('GET', `api/v1/exports/${enc(id)}`, { user });
+    }
+    /** The finished export: one JSON archive (`format: "recordare-export/1"`). */
+    exportArchive(user, id) {
+        return this.http.request('GET', `api/v1/exports/${enc(id)}/archive`, { user });
+    }
     /** Closes the MCP sessions (on shutdown). */
     close() {
         return this.mcp.close();