@arkimedehq/recordare-client 0.2.0 → 0.4.0

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. */
@@ -66,8 +79,33 @@ export interface IngestConversation {
     source?: ConversationSource;
     channel?: string;
     title?: string;
+    /** A one-to-one chat (true) or a group (false), when the platform knows: a link code is never accepted in a group (D51). */
+    direct?: boolean;
     participants?: IngestParticipant[];
 }
+/** A one-time code the holder sends from a channel to link that identity to themselves (D51; ten minutes, one use). */
+export interface LinkCode {
+    code: string;
+    expiresAt: string;
+}
+/** The identities that speak as the memory's "I", and the claims waiting for the holder's confirmation (D51). */
+export interface HolderIdentities {
+    linked: Array<{
+        id: string;
+        channel: string | null;
+        client: string | null;
+        externalId: string;
+        linkedAt: string;
+    }>;
+    pending: Array<{
+        id: string;
+        channel: string | null;
+        client: string | null;
+        externalId: string;
+        displayName: string | null;
+        claimedAt: string;
+    }>;
+}
 export interface IngestMessage {
     /** The platform's own stable id: Recordare deduplicates on it, so a resend never duplicates. */
     externalId: string;
@@ -99,6 +137,52 @@ export interface IngestResult {
     duplicates: number;
     conflicts: string[];
 }
+/** One voice of a room transcript (continuous listening, `ingestRoom`). */
+export interface RoomSpeaker {
+    /** The transcript-local reference messages use in `speakerRef`. */
+    ref: string;
+    displayName?: string;
+    /** The platform's user id of a speaker with an account: in their own memory their words are theirs. */
+    user?: string;
+    /** Otherwise (or as well) a channel identity, e.g. a voice profile: a contact in every recipient's memory. */
+    identity?: ParticipantIdentity;
+}
+/**
+ * What a home device heard in a room (WORK_PLAN 6.5 (4)), fanned out by Recordare to the memories of `recipients` (the
+ * platform's user ids of the people present whose memory is on — the platform's switch, D50): each gets it as an
+ * `ambient` conversation with the same external id, so edits and deletions go through the per-user calls.
+ */
+export interface RoomRequest {
+    conversation: {
+        externalId: string;
+        channel?: string;
+        title?: string;
+    };
+    speakers: RoomSpeaker[];
+    recipients: string[];
+    messages: Array<{
+        externalId: string;
+        /** Missing when the device could not tell who spoke: "someone" in every memory. */
+        speakerRef?: string;
+        content: string;
+        /** ISO 8601 with offset. */
+        sentAt: string;
+        upsert?: boolean;
+    }>;
+    hints?: {
+        conversationEnded?: boolean;
+    };
+}
+export interface RoomResult {
+    /** One per recipient, in the request's order; `conversationId` is that memory's conversation. */
+    recipients: Array<{
+        user: string;
+        conversationId: string | null;
+        accepted: number;
+        duplicates: number;
+        conflicts: string[];
+    }>;
+}
 export type PlanStatus = 'open' | 'confirmed' | 'cancelled' | 'rescheduled' | 'unresolved';
 export type Precision = 'minute' | 'day' | 'month' | 'year' | 'approximate' | 'unknown';
 export interface Episode {
@@ -193,10 +277,81 @@ export interface Note {
     pinned: boolean;
     pending: boolean;
     inferred: boolean;
+    /** A recurring pattern the memory drew from its episodes (inferred, never pending; WORK_PLAN 5.4). */
+    pattern: boolean;
     authorRole: string;
     supportCount: number;
     recordedAt: string;
 }
+/** The messages behind a fact or a note; text only from the client's own conversations (`otherClient` otherwise). */
+export type ItemEvidence = Array<{
+    messageId?: string;
+    conversation?: string;
+    role: string;
+    author?: string | null;
+    sentAt: string;
+    text?: string;
+    otherClient?: true;
+}>;
+export interface FactDetail extends Fact {
+    authorRole: string;
+    /** The fact this one corrected (a correction by the person). */
+    corrects: string | null;
+    recordedAt: string;
+    evidence: ItemEvidence;
+    /** Episodes the fact was drawn from. */
+    episodeIds: string[];
+}
+export interface NoteDetail extends Note {
+    status: 'current' | 'superseded' | 'corrected';
+    supersedes: string | null;
+    corrects: string | null;
+    evidence: ItemEvidence;
+    episodeIds: string[];
+}
+/** One entry of the notes change feed; `note` is the note as it is now, null once forgotten. */
+export interface NoteChange {
+    seq: number;
+    noteId: string;
+    change: 'created' | 'updated' | 'corrected' | 'confirmed' | 'forgotten' | 'retired';
+    at: string;
+    /** For `updated` / `corrected`: the note this one took the place of (a copy of it should follow), else null. */
+    replaces: string | null;
+    note: (Note & {
+        status: string;
+    }) | null;
+}
+export interface MemorySettings {
+    locale: string;
+    timezone: string;
+    /** null: the installation default (`effectiveQualityProfile`). */
+    qualityProfile: 'economy' | 'balanced' | 'full' | null;
+    effectiveQualityProfile: 'economy' | 'balanced' | 'full';
+}
+export interface UsageTotals {
+    calls: number;
+    inputTokens: number;
+    cachedInputTokens: number;
+    outputTokens: number;
+    failed: number;
+}
+export interface Usage extends UsageTotals {
+    from: string;
+    to: string;
+    byPrompt: Array<UsageTotals & {
+        prompt: string;
+    }>;
+    byDay: Array<UsageTotals & {
+        day: string;
+    }>;
+}
+export interface ExportJob {
+    id: string;
+    status: 'running' | 'done' | 'failed';
+    createdAt: string;
+    finishedAt: string | null;
+    bytes: number | null;
+}
 /** Size of the parts `learnSource` sends a big text in (UTF-8 bytes; the service's default request limit is 16 MB). */
 export declare const SOURCE_PART_BYTES: number;
 export type SourceKind = 'document' | 'page' | 'note' | 'book' | 'own_text';
@@ -250,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/index.d.ts

@@ -6,4 +6,5 @@ export { RecordareClient } from './client.js';
 export { RecordareMcp, type McpOptions, type Tool, type ToolResult } from './mcp.js';
 export { PersonDirectory, type Person, type PersonDirectoryOptions } from './people.js';
 export { TOOLS } from './tools.js';
+export { isLinkCode, LINK_CODE, LINK_CODE_INSTRUCTION } from './links.js';
 export { afterFailure, backoffMs, DEFAULT_DELIVERY, type DeliveryPolicy, type Next } from './delivery.js';

package/dist/index.js

@@ -8,4 +8,5 @@ export { RecordareClient } from './client.js';
 export { RecordareMcp } from './mcp.js';
 export { PersonDirectory } from './people.js';
 export { TOOLS } from './tools.js';
+export { isLinkCode, LINK_CODE, LINK_CODE_INSTRUCTION } from './links.js';
 export { afterFailure, backoffMs, DEFAULT_DELIVERY } from './delivery.js';

package/dist/links.d.ts

@@ -0,0 +1,10 @@
+/**
+ * D51 — linking the holder's channel identity by one-time code. The holder makes a code (`RecordareClient.linkCode`),
+ * sends it to the agent from the channel, then confirms the claim (`holderIdentities` / `confirmHolderClaim`). Recordare
+ * never stores the code's message; a host that sees the message before its model can tell the model what it is.
+ */
+/** A message that is only a link code (dashes and a final dot optional, any case) — the service's own pattern. */
+export declare const LINK_CODE: RegExp;
+export declare function isLinkCode(text: string): boolean;
+/** What a host adds for its model when the user's message is a link code (the model would otherwise try to answer it). */
+export declare const LINK_CODE_INSTRUCTION: string;

package/dist/links.js

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright © 2026 Andrea Genovese
+/**
+ * D51 — linking the holder's channel identity by one-time code. The holder makes a code (`RecordareClient.linkCode`),
+ * sends it to the agent from the channel, then confirms the claim (`holderIdentities` / `confirmHolderClaim`). Recordare
+ * never stores the code's message; a host that sees the message before its model can tell the model what it is.
+ */
+/** A message that is only a link code (dashes and a final dot optional, any case) — the service's own pattern. */
+export const LINK_CODE = /^\s*RCD-?[0-9A-Z]{4}-?[0-9A-Z]{4}\.?\s*$/i;
+export function isLinkCode(text) {
+    return LINK_CODE.test(text);
+}
+/** What a host adds for its model when the user's message is a link code (the model would otherwise try to answer it). */
+export const LINK_CODE_INSTRUCTION = 'The user\'s last message is a one-time code that links their account on this channel to their '
+    + 'memory (Recordare); it is handled automatically. Reply only, briefly and in the user\'s language, that the code was '
+    + 'received and that they now confirm the link where they created the code. Do not repeat the code.';

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.2.0' });
+        const client = new Client(this.options.clientInfo ?? { name: 'recordare-client', version: '0.4.0' });
         await client.connect(transport);
         return client;
     }

package/dist/people.d.ts

@@ -2,9 +2,9 @@
  * Who each of the platform's users is in Recordare, cached: the memory (memoryId), its mode and the Atlas
  * address. Recordare has no consent flag (D50): the platform's own switch (`enabled`) decides whether it is contacted.
  * The synchronous readers never wait on Recordare: they answer from the cache (even if stale) and refresh in the
- * background. Each lookup also keeps the person's name in sync with the platform's profile.
+ * background. Each lookup also keeps the person's name and gender in sync with the platform's profile.
  */
-import { type MemoryMode } from './contract.js';
+import { type MemoryGender, type MemoryMode } from './contract.js';
 import { type RecordareClient } from './client.js';
 export interface Person {
     /** null = not known yet (not opted in on the platform, or Recordare unreachable before the first lookup). */
@@ -18,6 +18,8 @@ export interface PlatformUser {
     enabled: boolean;
     /** The current profile name: the person's name in Recordare follows it. */
     name?: string | null;
+    /** The profile's gender: the first person's gender in gendered languages follows it (not set = left as it is). */
+    gender?: MemoryGender | null;
 }
 export interface PersonDirectoryOptions {
     /** How long a lookup is trusted; default 5 minutes. */
@@ -26,7 +28,7 @@ export interface PersonDirectoryOptions {
     user: (user: string) => Promise<PlatformUser | null>;
     /** A person resolved (e.g. to store the memoryId with the platform's user). */
     onResolved?: (user: string, person: Person) => void | Promise<void>;
-    /** Called when a lookup or a rename fails (the cache keeps the last known person). */
+    /** Called when a lookup or a settings update fails (the cache keeps the last known person). */
     onError?: (user: string, err: unknown) => void;
 }
 export declare class PersonDirectory {

package/dist/people.js

@@ -51,8 +51,12 @@ export class PersonDirectory {
                 return remember({ memoryId: last?.memoryId ?? null, mode: last?.mode ?? null, atlasUrl: last?.atlasUrl ?? null });
             const me = await this.client.me(user);
             const name = platform.name?.trim().slice(0, 100);
-            if (name && me.displayName !== name) {
-                await this.client.updateMe(user, { displayName: name }).catch((err) => this.options.onError?.(user, err));
+            const changed = {
+                ...(name && me.displayName !== name ? { displayName: name } : {}),
+                ...(platform.gender && me.gender !== platform.gender ? { gender: platform.gender } : {}),
+            };
+            if (Object.keys(changed).length) {
+                await this.client.updateMe(user, changed).catch((err) => this.options.onError?.(user, err));
             }
             const person = { memoryId: me.memoryId, mode: me.mode, atlasUrl: me.atlasUrl ?? null };
             await this.options.onResolved?.(user, person);

package/dist/tools.d.ts

@@ -76,7 +76,7 @@ export declare const TOOLS: readonly [{
 }, {
     readonly name: "log_episode";
     readonly title: "Note something that happened or is planned";
-    readonly description: "Explicit capture (\"note that today I serviced the car\"). Resolve the date yourself (ISO).";
+    readonly description: "Explicit capture (\"note that today I serviced the car\"). Resolve the date yourself (ISO). Conversations are remembered automatically: use it only when explicitly asked, and never ask whether to remember or save something.";
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {
@@ -115,7 +115,7 @@ export declare const TOOLS: readonly [{
 }, {
     readonly name: "remember";
     readonly title: "Remember something";
-    readonly description: "Explicit \"remember that…\" about preferences, habits, values, knowledge.";
+    readonly description: "Explicit \"remember that…\" about preferences, habits, values, knowledge. Conversations are remembered automatically: use it only when explicitly asked, and never ask whether to remember or save something.";
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {
@@ -147,7 +147,7 @@ export declare const TOOLS: readonly [{
 }, {
     readonly name: "search_episodes";
     readonly title: "Search what happened";
-    readonly description: "Search your memory of what happened: what you lived, did, planned or learned, and what happened to the people you know (events, plans, changes), with dates and status. Each item has a subject: you (written in the first person), a person by name, someone, or undecided. Use `from`/`to` (ISO dates, inclusive; see resolve_period) for questions about a period. mode: \"search\" = most relevant, \"list\" = chronological in the period (overviews, counting), \"latest\" = most recent first (\"when did I last…\").";
+    readonly description: "Search your memory of what happened: what you lived, did, planned or learned, and what happened to the people you know (events, plans, changes), with dates and status. Each item has a subject: you (written in the first person), a person by name, someone, or undecided. Use `from`/`to` (ISO dates, inclusive; see resolve_period) for questions about a period; a vague span (\"lately\", \"these weeks\") is not a period: leave them out. mode: \"search\" = most relevant, \"list\" = chronological in the period (overviews, counting), \"latest\" = most recent first (\"when did I last…\"). An item or chat excerpt marked `heard` was overheard in the room by a listening device, not said to you: tell it as heard at home, and its speaker may have been misrecognised — what it says of you may be someone else's. A chat excerpt by `assistant` is your own earlier reply: what you told them then (advice, a recipe, a name), not something they lived.";
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {
@@ -203,7 +203,7 @@ export declare const TOOLS: readonly [{
 }, {
     readonly name: "search_memory";
     readonly title: "Search what you know about yourself and others";
-    readonly description: "Search your memory of preferences, habits, values, relationships, knowledge and current state (car, home, job…) — yours and of the people you know; each item has its subject. Use `as_of` (ISO date) for \"what was it on that date\" questions; each fact comes with its history.";
+    readonly description: "Search your memory of preferences, habits, values, relationships, knowledge and current state (car, home, job…) — yours and of the people you know; each item has its subject. Use `as_of` (ISO date) for \"what was it on that date\" questions; each fact comes with its history. A note with `pattern` is a habit you noticed yourself in repeated episodes, not something said: tell it as such.";
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {

package/dist/tools.js

@@ -100,7 +100,7 @@ export const TOOLS = [
     {
         "name": "log_episode",
         "title": "Note something that happened or is planned",
-        "description": "Explicit capture (\"note that today I serviced the car\"). Resolve the date yourself (ISO).",
+        "description": "Explicit capture (\"note that today I serviced the car\"). Resolve the date yourself (ISO). Conversations are remembered automatically: use it only when explicitly asked, and never ask whether to remember or save something.",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -150,7 +150,7 @@ export const TOOLS = [
     {
         "name": "remember",
         "title": "Remember something",
-        "description": "Explicit \"remember that…\" about preferences, habits, values, knowledge.",
+        "description": "Explicit \"remember that…\" about preferences, habits, values, knowledge. Conversations are remembered automatically: use it only when explicitly asked, and never ask whether to remember or save something.",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -196,7 +196,7 @@ export const TOOLS = [
     {
         "name": "search_episodes",
         "title": "Search what happened",
-        "description": "Search your memory of what happened: what you lived, did, planned or learned, and what happened to the people you know (events, plans, changes), with dates and status. Each item has a subject: you (written in the first person), a person by name, someone, or undecided. Use `from`/`to` (ISO dates, inclusive; see resolve_period) for questions about a period. mode: \"search\" = most relevant, \"list\" = chronological in the period (overviews, counting), \"latest\" = most recent first (\"when did I last…\").",
+        "description": "Search your memory of what happened: what you lived, did, planned or learned, and what happened to the people you know (events, plans, changes), with dates and status. Each item has a subject: you (written in the first person), a person by name, someone, or undecided. Use `from`/`to` (ISO dates, inclusive; see resolve_period) for questions about a period; a vague span (\"lately\", \"these weeks\") is not a period: leave them out. mode: \"search\" = most relevant, \"list\" = chronological in the period (overviews, counting), \"latest\" = most recent first (\"when did I last…\"). An item or chat excerpt marked `heard` was overheard in the room by a listening device, not said to you: tell it as heard at home, and its speaker may have been misrecognised — what it says of you may be someone else's. A chat excerpt by `assistant` is your own earlier reply: what you told them then (advice, a recipe, a name), not something they lived.",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -260,7 +260,7 @@ export const TOOLS = [
     {
         "name": "search_memory",
         "title": "Search what you know about yourself and others",
-        "description": "Search your memory of preferences, habits, values, relationships, knowledge and current state (car, home, job…) — yours and of the people you know; each item has its subject. Use `as_of` (ISO date) for \"what was it on that date\" questions; each fact comes with its history.",
+        "description": "Search your memory of preferences, habits, values, relationships, knowledge and current state (car, home, job…) — yours and of the people you know; each item has its subject. Use `as_of` (ISO date) for \"what was it on that date\" questions; each fact comes with its history. A note with `pattern` is a habit you noticed yourself in repeated episodes, not something said: tell it as such.",
         "inputSchema": {
             "type": "object",
             "properties": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkimedehq/recordare-client",
-  "version": "0.2.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,9 +2,10 @@
 // Copyright © 2026 Andrea Genovese
 
 import {
-  CONVERSATION_HEADER, type Digest, type Episode, type EpisodeDetail, type EpisodeQuery, type Fact, type IngestRequest, type IngestResult,
-  type LearnSource, type LearnSourceResult, MAX_MESSAGES_PER_REQUEST, type Me, type MeSettings, type MemoryContext, type Note, type PlanStatus,
-  type Precision, type Source, SOURCE_PART_BYTES,
+  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,
 } from './contract.js';
 import { MemoryNotEmptyError, RecordareHttpError } from './errors.js';
 import { type ClientOptions, Http } from './http.js';
@@ -49,6 +50,39 @@ 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 });
+  }
+
+  /** The identities that speak as the memory's "I" and the claims waiting for confirmation (D51). */
+  holderIdentities(user: string): Promise<HolderIdentities> {
+    return this.http.request<HolderIdentities>('GET', 'api/v1/me/identities', { user });
+  }
+
+  /** Confirms a claim: that channel identity is the holder from now on. */
+  async confirmHolderClaim(user: string, id: string): Promise<void> {
+    await this.http.request('POST', `api/v1/me/identities/pending/${encodeURIComponent(id)}/confirm`, { user });
+  }
+
+  /** Rejects a claim (not the holder). */
+  async rejectHolderClaim(user: string, id: string): Promise<void> {
+    await this.http.request('DELETE', `api/v1/me/identities/pending/${encodeURIComponent(id)}`, { user });
+  }
+
+  /** Unlinks one of the holder's identities. */
+  async unlinkHolderIdentity(user: string, id: string): Promise<void> {
+    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.
@@ -74,21 +108,46 @@ 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: RoomRequest): Promise<RoomResult> {
+    const total = new Map<string, RoomResult['recipients'][number]>();
+    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<RoomResult>('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: 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. */
@@ -159,6 +218,14 @@ export class RecordareClient {
     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: string, period: { from: string; to: string; keepRaw?: boolean }): Promise<{ episodes: number; messages: number; facts: number; notes: number }> {
+    return this.http.request('POST', 'api/v1/forget', { user, body: period });
+  }
+
   digests(user: string, query: { level?: 'day' | 'month'; from?: string; to?: string } = {}): Promise<Digest[]> {
     return this.http.request('GET', `api/v1/digests${qs(query)}`, { user });
   }
@@ -167,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 });
   }
@@ -190,6 +262,68 @@ export class RecordareClient {
     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: string, episode: { content: string; kind?: 'event' | 'plan'; occurredAt?: string; occurredUntil?: string;
+    datePrecision?: Exclude<Precision, 'unknown' | 'minute'>; place?: string; people?: string[] }): Promise<string> {
+    return (await this.http.request<{ id: string }>('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: string, note: { content: string; category?: Note['category'] }): Promise<string> {
+    return (await this.http.request<{ id: string }>('POST', 'api/v1/notes', { user, body: note })).id;
+  }
+
+  fact(user: string, id: string): Promise<FactDetail> {
+    return this.http.request('GET', `api/v1/facts/${enc(id)}`, { user });
+  }
+
+  note(user: string, id: string): Promise<NoteDetail> {
+    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: string, id: string, fix: { value: string | null; validFrom?: string; datePrecision?: Exclude<Precision, 'unknown' | 'minute'> }): Promise<string> {
+    return (await this.http.request<{ id: string }>('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: string, id: string, fix: { content: string; category?: Note['category'] }): Promise<string> {
+    return (await this.http.request<{ id: string }>('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: string, query: { since?: number; limit?: number } = {}): Promise<{ items: NoteChange[]; next: number; more: boolean }> {
+    return this.http.request('GET', `api/v1/notes/changes${qs(query)}`, { user });
+  }
+
+  settings(user: string): Promise<MemorySettings> {
+    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: string, patch: { locale?: string; timezone?: string; qualityProfile?: MemorySettings['qualityProfile'] }): Promise<MemorySettings> {
+    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: string, query: { from?: string; to?: string } = {}): Promise<Usage> {
+    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: string): Promise<ExportJob> {
+    return this.http.request('POST', 'api/v1/exports', { user });
+  }
+
+  exportJob(user: string, id: string): Promise<ExportJob> {
+    return this.http.request('GET', `api/v1/exports/${enc(id)}`, { user });
+  }
+
+  /** The finished export: one JSON archive (`format: "recordare-export/1"`). */
+  exportArchive(user: string, id: string): Promise<Record<string, unknown>> {
+    return this.http.request('GET', `api/v1/exports/${enc(id)}/archive`, { user });
+  }
+
   /** Closes the MCP sessions (on shutdown). */
   close(): Promise<void> {
     return this.mcp.close();