@arkimedehq/recordare-client 0.1.0 → 0.2.0

package/src/client.ts

@@ -3,7 +3,8 @@
 
 import {
   CONVERSATION_HEADER, type Digest, type Episode, type EpisodeDetail, type EpisodeQuery, type Fact, type IngestRequest, type IngestResult,
-  MAX_MESSAGES_PER_REQUEST, type Me, type MeSettings, type MemoryContext, type Note, type PlanStatus, type Precision,
+  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,
 } from './contract.js';
 import { MemoryNotEmptyError, RecordareHttpError } from './errors.js';
 import { type ClientOptions, Http } from './http.js';
@@ -20,7 +21,7 @@ function qs(query: object): string {
 }
 
 /**
- * Recordare for one platform (docs/INTEGRATION.md): who a user is and their consent, their settings, the conversations
+ * Recordare for one platform (docs/INTEGRATION.md): who a user is, their settings, the conversations
  * the platform sends, deletions, and recall over MCP. Stateless apart from MCP sessions; a host keeps its own outbox and
  * cache (see `delivery` and `PersonDirectory`).
  */
@@ -33,12 +34,12 @@ export class RecordareClient {
     this.mcp = new RecordareMcp(this.http, options.mcp);
   }
 
-  /** The person behind `user` (auto-provisioned when the client allows it), their consent and kind of memory. */
+  /** The memory behind `user` (auto-provisioned when the client allows it), its mode and gender. */
   me(user: string): Promise<Me> {
     return this.http.request<Me>('GET', 'api/v1/me', { user });
   }
 
-  /** The person's settings from the platform: the name (keep it in sync on every rename) and the kind of memory. */
+  /** The memory's settings from the platform: the name (keep it in sync on every rename), the mode and the gender. */
   async updateMe(user: string, settings: MeSettings): Promise<void> {
     try {
       await this.http.request('PATCH', 'api/v1/me', { user, body: settings });
@@ -50,10 +51,10 @@ export class RecordareClient {
 
   /**
    * Sends messages of one conversation, split into requests of at most MAX_MESSAGES_PER_REQUEST. Idempotent: Recordare
-   * deduplicates on each message's externalId. Before consent nothing is stored (`stored: false`).
+   * deduplicates on each message's externalId. Recordare always stores (D50): the on/off switch is the platform's.
    */
   async ingest(user: string, req: IngestRequest): Promise<IngestResult> {
-    const total: IngestResult = { conversationId: null, accepted: 0, duplicates: 0, conflicts: [], stored: true };
+    const total: IngestResult = { conversationId: null, accepted: 0, duplicates: 0, conflicts: [] };
     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<IngestResult>('POST', 'api/v1/ingest/messages', {
@@ -69,7 +70,6 @@ export class RecordareClient {
       total.accepted += part.accepted;
       total.duplicates += part.duplicates;
       total.conflicts.push(...part.conflicts);
-      total.stored &&= part.stored;
     }
     return total;
   }
@@ -83,6 +83,19 @@ export class RecordareClient {
     return this.http.request<MemoryContext>('POST', 'api/v1/context', { user, body: { query }, 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 } : {}) } });
+  }
+
+  /** The conversation ended (session closed, /new): extraction runs now. A conversation Recordare never had is done. */
+  async endConversation(user: string, conversation: string): Promise<void> {
+    await this.gone(this.http.request('POST', `api/v1/ingest/conversations/${enc(conversation)}/end`, { user }));
+  }
+
   /** An edited message: Recordare re-extracts what depended on it. */
   async editMessage(user: string, conversation: string, message: string, content: string): Promise<void> {
     await this.http.request('PATCH', `api/v1/ingest/conversations/${enc(conversation)}/messages/${enc(message)}`, { user, body: { content } });
@@ -98,6 +111,33 @@ export class RecordareClient {
     await this.gone(this.http.request('DELETE', `api/v1/ingest/conversations/${enc(conversation)}`, { user }));
   }
 
+  // ── Learned sources (WORK_PLAN 8.9, D49): text the agent learns — the client turns files into text ─────────────
+
+  /**
+   * The agent learns a text. A big one is sent in parts (at paragraph boundaries, `partBytes` each); any size works.
+   * Sending the same `externalId` again replaces the source; the same first part again is a duplicate.
+   */
+  async learnSource(user: string, source: LearnSource, partBytes = SOURCE_PART_BYTES): Promise<LearnSourceResult> {
+    const [first = '', ...rest] = splitParts(source.text, partBytes);
+    let result = await this.http.request<LearnSourceResult>('POST', 'api/v1/ingest/sources', { user, body: { ...source, text: first, final: rest.length === 0 } });
+    if (result.duplicate) return result;
+    for (const [i, text] of rest.entries()) {
+      result = await this.http.request<LearnSourceResult>('POST', `api/v1/ingest/sources/${enc(source.externalId)}/parts`,
+        { user, body: { part: i + 1, text, final: i === rest.length - 1 } });
+    }
+    return result;
+  }
+
+  /** The agent forgets a source (its text and passages; episodes keep a "forgotten source" marker). One it never had counts as done. */
+  async forgetSource(user: string, externalId: string): Promise<void> {
+    await this.http.request('DELETE', `api/v1/ingest/sources/${enc(externalId)}`, { user });
+  }
+
+  /** What the agent learned, newest first. */
+  sources(user: string): Promise<Source[]> {
+    return this.http.request('GET', 'api/v1/sources', { user });
+  }
+
   // ── The diary (API.md §4): what Recordare remembers, shown to the person in the platform's UI ──────────────────
 
   /** The timeline, newest first; pass `nextCursor` back as `cursor` for the next page. */
@@ -163,3 +203,32 @@ export class RecordareClient {
     }
   }
 }
+
+/** A text in parts of at most `maxBytes` UTF-8 bytes, cut at paragraph boundaries (inside a long paragraph: at a space, else between characters). */
+export function splitParts(text: string, maxBytes: number): string[] {
+  const size = (t: string) => Buffer.byteLength(t, 'utf8');
+  if (size(text) <= maxBytes) return [text];
+  const parts: string[] = [];
+  let current = '';
+  const push = (piece: string) => {
+    const joined = current ? `${current}\n\n${piece}` : piece;
+    if (size(joined) <= maxBytes) { current = joined; return; }
+    if (current) parts.push(current);
+    current = piece;
+  };
+  for (const paragraph of text.split(/\n\s*\n/)) {
+    let rest = paragraph;
+    while (size(rest) > maxBytes) {
+      let end = rest.length;
+      while (end > 0 && size(rest.slice(0, end)) > maxBytes) end = Math.floor(end * 0.9);
+      const space = rest.lastIndexOf(' ', end);
+      let cut = space > end / 2 ? space : end;
+      if (/[\uD800-\uDBFF]/.test(rest.charAt(cut - 1))) cut--; // never between the halves of a surrogate pair
+      push(rest.slice(0, cut));
+      rest = rest.slice(cut).trimStart();
+    }
+    if (rest) push(rest);
+  }
+  if (current) parts.push(current);
+  return parts;
+}

package/src/contract.ts

@@ -9,7 +9,7 @@
 
 /** The client's user the request acts for (with a client key). */
 export const USER_HEADER = 'X-Recordare-User';
-/** The conversation a read happens in: Recordare resolves who will see the answer from it (viewer context). */
+/** The conversation a read or write happens in: evidence of MCP writes, the current turn left out of recall (D50: no viewer filter). */
 export const CONVERSATION_HEADER = 'X-Recordare-Conversation';
 
 /** Largest message content Recordare accepts (UTF-8 bytes). */
@@ -17,16 +17,20 @@ export const MAX_CONTENT_BYTES = 64 * 1024;
 /** Largest number of messages in one ingest request. */
 export const MAX_MESSAGES_PER_REQUEST = 500;
 
-/** A personal memory, or one shared by everyone using the account (an entity: a home device, a robot, a place). */
-export type MemoryKind = 'human' | 'entity';
+/**
+ * A personal memory (the account holder is "I": what arrives without a declared identity is the memory's own), or an
+ * entity's (a home device, a robot, a place: what arrives undeclared is "someone"'s) — D50.
+ */
+export type MemoryMode = 'personal' | 'entity';
+/** The grammatical gender of the memory's first person in gendered languages (default masculine). */
+export type MemoryGender = 'masculine' | 'feminine' | 'neutral';
 
 /** `GET api/v1/me`: who a request acts for. */
 export interface Me {
-  ownerId: string;
+  memoryId: string;
   displayName: string | null;
-  kind: MemoryKind;
-  /** The person's consent, given by the Recordare admin: until then ingest stores nothing. */
-  episodicEnabled: boolean;
+  mode: MemoryMode;
+  gender: MemoryGender;
   /** Recordare Atlas, when installed: link it for the platform's admins only (it shows every person's activity). */
   atlasUrl?: string;
   via: string;
@@ -38,7 +42,9 @@ export interface MeSettings {
   /** Follows the platform's profile: send it again whenever the user renames themselves. */
   displayName?: string;
   /** Accepted only while the memory is empty (else MemoryNotEmptyError). */
-  kind?: MemoryKind;
+  mode?: MemoryMode;
+  /** From the account's profile; changes any time. */
+  gender?: MemoryGender;
 }
 
 export type ParticipantIdentity = { externalUserId: string } | { channel: string; externalId: string };
@@ -46,14 +52,21 @@ export type ParticipantIdentity = { externalUserId: string } | { channel: string
 export interface IngestParticipant {
   /** The conversation-local reference messages use in `authorRef`. */
   ref: string;
-  role: 'owner' | 'assistant' | 'other';
+  role: 'holder' | 'assistant' | 'other';
   displayName?: string;
-  /** A verified identity on the platform: lets Recordare link the participant to a known person. */
+  /**
+   * The participant's id on the platform (its user id) or on a channel: Recordare links it to a contact of this memory
+   * (created on first sight) — never to another memory.
+   */
   identity?: ParticipantIdentity;
 }
 
-/** Where a conversation comes from (`mcp_tool` is the service's own, never sent by a client). */
-export type ConversationSource = 'chat' | 'voice' | 'import_chat' | 'import_social' | 'import_email' | 'import_notes' | 'interview';
+/**
+ * Where a conversation comes from (`mcp_tool` is the service's own, never sent by a client). `document`: a document
+ * given to the agent; `perception`: what a device perceives; `ambient`: continuous listening.
+ */
+export type ConversationSource = 'chat' | 'voice' | 'import_chat' | 'import_social' | 'import_email' | 'import_notes' | 'interview'
+  | 'document' | 'perception' | 'ambient';
 
 export interface IngestConversation {
   /** The platform's own stable id of the conversation. */
@@ -77,6 +90,8 @@ export interface IngestMessage {
   sentAt: string;
   /** Replace the stored content of an existing message (an edit). */
   upsert?: boolean;
+  /** The agent's own content (knowledge given to it, its perceptions, a document); `user` or `other` messages only. */
+  own?: boolean;
 }
 
 export interface IngestRequest {
@@ -89,12 +104,11 @@ export interface IngestRequest {
 }
 
 export interface IngestResult {
+  /** null only when no message was sent. */
   conversationId: string | null;
   accepted: number;
   duplicates: number;
   conflicts: string[];
-  /** false = consent not given yet: nothing was stored. */
-  stored: boolean;
 }
 
 // ── The diary: read / write API for host UIs (API.md §4) ─────────────────────────────────────────────────────────
@@ -173,9 +187,55 @@ export interface Note {
   recordedAt: string;
 }
 
+/** 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;
+
+export type SourceKind = 'document' | 'page' | 'note' | 'book' | 'own_text';
+
+/** `POST api/v1/ingest/sources` (WORK_PLAN 8.9, D49): a text the agent learns — the client turns files into text. */
+export interface LearnSource {
+  /** The client's own id for the source: sending it again replaces it (a new version). */
+  externalId: string;
+  title: string;
+  kind?: SourceKind;
+  author?: string;
+  uri?: string;
+  language?: string;
+  learnedAt?: string;
+  /** Who gave it: "me" (the memory's self), "someone", or a person by name. Default "me". */
+  providedBy?: 'me' | 'someone' | { name: string };
+  /** The conversation it was learned in: its extraction then tells of it. */
+  conversation?: { externalId: string };
+  text: string;
+}
+
+export interface LearnSourceResult {
+  sourceId: string;
+  status: 'receiving' | 'indexing' | 'ready';
+  parts: number;
+  passages: number;
+  duplicate: boolean;
+}
+
+/** `GET api/v1/sources`: a learned source (the Diary's "what I learned"). */
+export interface Source {
+  id: string;
+  externalId: string;
+  title: string;
+  kind: string;
+  author: string | null;
+  uri: string | null;
+  providedBy: { kind: 'self' } | { kind: 'someone' } | { kind: 'contact'; name: string };
+  learnedAt: string;
+  status: 'receiving' | 'indexing' | 'ready';
+  chars: number;
+  passages: number;
+  episodeIds: string[];
+}
+
 /** `POST api/v1/context`: the memories relevant to the message a host is about to answer (WORK_PLAN 5.7). */
 export interface MemoryContext {
-  /** A fenced `<memory-context>` block to append to the prompt, or null (nothing relevant, not owner-only, or off). */
+  /** A fenced `<memory-context>` block to append to the prompt, or null (nothing relevant, or off). */
   block: string | null;
   items: number;
 }

package/src/errors.ts

@@ -34,10 +34,10 @@ export class RecordareUnavailableError extends Error {
   }
 }
 
-/** The memory kind can change only while the memory is empty (`PATCH /me {kind}` → 409). */
+/** The memory mode can change only while the memory is empty (`PATCH /me {mode}` → 409). */
 export class MemoryNotEmptyError extends Error {
   constructor() {
-    super('The memory kind can change only while the memory is empty');
+    super('The memory mode can change only while the memory is empty');
     this.name = 'MemoryNotEmptyError';
   }
 }

package/src/index.ts

@@ -7,5 +7,6 @@ export * from './errors.js';
 export { type ClientOptions, type FetchLike, parseRetryAfter } from './http.js';
 export { RecordareClient } from './client.js';
 export { RecordareMcp, type McpOptions, type Tool, type ToolResult } from './mcp.js';
-export { PersonDirectory, type ConsentState, type Person, type PersonDirectoryOptions } from './people.js';
+export { PersonDirectory, type Person, type PersonDirectoryOptions } from './people.js';
+export { TOOLS } from './tools.js';
 export { afterFailure, backoffMs, DEFAULT_DELIVERY, type DeliveryPolicy, type Next } from './delivery.js';

package/src/mcp.ts

@@ -2,8 +2,8 @@
 // Copyright © 2026 Andrea Genovese
 
 /**
- * Recall over MCP with the official SDK (streamable HTTP). Recordare fixes the owner when a session starts and resolves
- * the viewer context from the conversation header (docs/API.md §1), so a session belongs to one user AND one
+ * Recall over MCP with the official SDK (streamable HTTP). Recordare fixes the memory when a session starts and resolves
+ * the conversation from its header (docs/API.md §1: evidence of writes), so a session belongs to one user AND one
  * conversation: both headers are bound here, in code — neither the LLM nor the user can change them. Sessions are
  * reused (bounded, least recently used closed first) and an expired one is re-opened once.
  */
@@ -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.1.0' });
+    const client = new Client(this.options.clientInfo ?? { name: 'recordare-client', version: '0.2.0' });
     await client.connect(transport);
     return client;
   }

package/src/people.ts

@@ -2,21 +2,18 @@
 // Copyright © 2026 Andrea Genovese
 
 /**
- * Who each of the platform's users is in Recordare, cached: the person (ownerId), their consent, the kind of memory and
- * the Atlas address. 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.
+ * 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.
  */
-import { type MemoryKind } from './contract.js';
+import { type MemoryMode } from './contract.js';
 import { type RecordareClient } from './client.js';
 
-/** The person's memory as the platform shows it: consent given, not yet, or Recordare unreachable. */
-export type ConsentState = 'waiting_activation' | 'active' | 'unknown';
-
 export interface Person {
-  ownerId: string | null;
-  /** true / false, null = unknown (Recordare unreachable). */
-  consent: boolean | null;
-  kind: MemoryKind | null;
+  /** null = not known yet (not opted in on the platform, or Recordare unreachable before the first lookup). */
+  memoryId: string | null;
+  mode: MemoryMode | null;
   atlasUrl: string | null;
 }
 
@@ -33,7 +30,7 @@ export interface PersonDirectoryOptions {
   ttlMs?: number;
   /** The user on the platform; null = unknown user (treated as not enabled). */
   user: (user: string) => Promise<PlatformUser | null>;
-  /** A person resolved (e.g. to store the ownerId with the platform's user). */
+  /** 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). */
   onError?: (user: string, err: unknown) => void;
@@ -57,8 +54,8 @@ export class PersonDirectory {
   }
 
   /** A person known from the host's own storage (e.g. after a restart), marked stale so it is refreshed on first use. */
-  seed(user: string, ownerId: string): void {
-    if (!this.cache.has(user)) this.cache.set(user, { ownerId, consent: null, kind: null, atlasUrl: null, until: 0 });
+  seed(user: string, memoryId: string): void {
+    if (!this.cache.has(user)) this.cache.set(user, { memoryId, mode: null, atlasUrl: null, until: 0 });
   }
 
   /** Forgets a user (e.g. after their switch or name changed): the next read asks Recordare again. */
@@ -66,23 +63,6 @@ export class PersonDirectory {
     this.cache.delete(user);
   }
 
-  /** Users whose consent is known to be off: a sender skips them (nothing is buffered before consent). */
-  knownOff(): string[] {
-    return [...this.cache].filter(([, e]) => e.consent === false).map(([u]) => u);
-  }
-
-  /** Re-checks now, waiting at most `timeoutMs`; falls back to the last known state. */
-  async status(user: string, timeoutMs = 3_000): Promise<ConsentState> {
-    let timer: ReturnType<typeof setTimeout> | undefined;
-    const fresh = await Promise.race([
-      this.refresh(user).catch(() => undefined),
-      new Promise<undefined>((r) => { timer = setTimeout(() => r(undefined), timeoutMs); }),
-    ]);
-    if (timer) clearTimeout(timer);
-    const consent = (fresh ?? this.cache.get(user))?.consent ?? null;
-    return consent === true ? 'active' : consent === false ? 'waiting_activation' : 'unknown';
-  }
-
   /** Asks Recordare now (one request in flight per user). */
   refresh(user: string): Promise<Person> {
     const running = this.inflight.get(user);
@@ -102,18 +82,18 @@ export class PersonDirectory {
     try {
       const platform = await this.options.user(user);
       // Not opted in on the platform: never contact Recordare; a person already known stays known (e.g. for tracing).
-      if (!platform?.enabled) return remember({ ownerId: last?.ownerId ?? null, consent: null, kind: last?.kind ?? null, atlasUrl: last?.atlasUrl ?? null });
+      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 person: Person = { ownerId: me.ownerId, consent: me.episodicEnabled, kind: me.kind, atlasUrl: me.atlasUrl ?? null };
+      const person: Person = { memoryId: me.memoryId, mode: me.mode, atlasUrl: me.atlasUrl ?? null };
       await this.options.onResolved?.(user, person);
       return remember(person);
     } catch (err) {
       this.options.onError?.(user, err);
-      return remember({ ownerId: last?.ownerId ?? null, consent: null, kind: last?.kind ?? null, atlasUrl: last?.atlasUrl ?? null });
+      return remember({ memoryId: last?.memoryId ?? null, mode: last?.mode ?? null, atlasUrl: last?.atlasUrl ?? null });
     }
   }
 }