@arkimedehq/recordare-client 0.2.0 → 0.4.0

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. */
@@ -74,9 +79,20 @@ 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;
@@ -111,6 +127,43 @@ export interface IngestResult {
   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[] }>;
+}
+
 // ── The diary: read / write API for host UIs (API.md §4) ─────────────────────────────────────────────────────────
 
 export type PlanStatus = 'open' | 'confirmed' | 'cancelled' | 'rescheduled' | 'unresolved';
@@ -182,11 +235,64 @@ 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 const SOURCE_PART_BYTES = 4 * 1024 * 1024;
 
@@ -234,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/index.ts

@@ -9,4 +9,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/src/links.ts

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

package/src/people.ts

@@ -5,9 +5,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 MeSettings, type MemoryGender, type MemoryMode } from './contract.js';
 import { type RecordareClient } from './client.js';
 
 export interface Person {
@@ -23,6 +23,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 {
@@ -32,7 +34,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;
 }
 
@@ -85,8 +87,12 @@ export class PersonDirectory {
       if (!platform?.enabled) 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: MeSettings = {
+        ...(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: Person = { memoryId: me.memoryId, mode: me.mode, atlasUrl: me.atlasUrl ?? null };
       await this.options.onResolved?.(user, person);

package/src/tools.ts

@@ -101,7 +101,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": {
@@ -151,7 +151,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": {
@@ -197,7 +197,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": {
@@ -261,7 +261,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": {