@arkimedehq/recordare-client 0.1.0 → 0.2.0

package/README.md

@@ -2,28 +2,40 @@
 
 *Italian version: [README_it.md](README_it.md).*
 
-The one client library every Recordare client uses (WORK_PLAN 6.7): identity and consent, the person's settings,
+> Since D50 (2026-10-09) Recordare has no consent flag: every memory stores what its client sends; the on/off switch
+> belongs to the client platform (WORK_PLAN 8.1).
+
+The one client library every Recordare client uses (WORK_PLAN 6.7): identity, the platform's on/off switch, the person's settings,
 ingest, edits and deletions, recall over MCP, and the delivery policy for a host's outbox. Built on standards, so a
 host adapts to them: MCP through the official SDK (streamable HTTP), errors as RFC 9457 problem details,
 `Retry-After` (RFC 9110) honoured, W3C trace context forwarded, native `fetch` (a host may pass its own, e.g. one
 enforcing an outbound-host policy). No host-specific code.
 
+On npm since Recordare v0.1.0: `npm install @arkimedehq/recordare-client` (Node ≥ 20, ES module).
+
 ```ts
 import { PersonDirectory, RecordareClient, afterFailure } from '@arkimedehq/recordare-client';
 
 const rc = new RecordareClient({ baseUrl: 'http://recordare:8080', apiKey: process.env.RECORDARE_API_KEY!,
   headers: () => traceHeaders() });                       // e.g. OpenTelemetry propagation.inject
 
-// Who the user is, their consent, kind of memory and Atlas address; the name follows the platform's profile.
+// Which memory the user's account opens, its mode (personal | entity) and Atlas address; the name follows 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' }) });
-await people.status('user-42');                           // 'active' | 'waiting_activation' | 'unknown'
+const person = await people.refresh('user-42');           // { memoryId, mode, atlasUrl }; peek() reads the cache
 
-// Ingest (split into requests of 500, idempotent on each externalId). Nothing is stored before consent.
+// Ingest (split into requests of 500, idempotent on each externalId): → { conversationId, accepted, duplicates, conflicts }.
 await rc.ingest('user-42', { conversation: { externalId: 'chat-1' }, messages: [
   { externalId: 'm1', role: 'user', content: 'Domani vado a Bologna', sentAt: new Date().toISOString() },
 ] });
+// The agent's own content (knowledge given to it, a perception, a document): `own: true` on a user / other message.
+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() },
+] });
+// 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' });
 
-// Recall: one MCP session per user AND conversation (the viewer context), both bound in code.
+// 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
 const res = await rc.mcp.callTool('user-42', 'chat-1', 'search_episodes', { query: 'Bologna' });
 
@@ -31,6 +43,29 @@ const res = await rc.mcp.callTool('user-42', 'chat-1', 'search_episodes', { quer
 const next = afterFailure(err, attempts);                 // { action: 'retry', delayMs } | { action: 'park', reason }
 ```
 
+## Before each turn, and at the end
+`contextWithTurn(user, turn)` stores the turn and returns its memory context in one round trip (`{block, items}`, the
+block to append to the system prompt; `context(user, conversation, query)` when the turn is already stored); `endConversation(user, conversation)` tells Recordare a conversation ended
+(session closed, /new) so extraction runs now. `TOOLS` holds the MCP tool schemas the service serves (name, title,
+description, JSON Schema), for hosts that must declare tools before connecting; the conformance suite keeps it in
+sync with the service.
+
+## Learned sources
+`learnSource(user, {externalId, title, text, kind?, author?, uri?, language?, learnedAt?, providedBy?, conversation?})`
+makes the agent learn a text (D49, WORK_PLAN 8.9: a manual, a page, a note — **text only**, the host converts files).
+Any size: a text bigger than `SOURCE_PART_BYTES` (4 MB, or the `partBytes` argument) is sent in parts cut at paragraph
+boundaries (`POST api/v1/ingest/sources` + `…/parts`); → `{sourceId, status, parts, passages, duplicate}`. The same
+`externalId` again replaces the source; `providedBy` is `'me'` (default), `'someone'` or `{name}`; `conversation:
+{externalId}` links it to the conversation it was learned in (that extraction tells of the learning).
+`forgetSource(user, externalId)` forgets it (one never sent counts as done); `sources(user)` lists what the agent
+learned (`Source[]`). The agent searches it with the MCP tool `search_knowledge`. Send only what the agent should
+learn, never a RAG's search results.
+
+```ts
+await rc.learnSource('user-42', { externalId: 'boiler-manual', title: 'Manuale della caldaia', text: manualText,
+  kind: 'document', providedBy: { name: 'Paolo' }, conversation: { externalId: 'chat-1' } });
+```
+
 ## 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).
@@ -41,13 +76,13 @@ Everything else is here, the same for every client.
 
 ## Conformance
 `service/test/conformance` runs this library against the real service in Recordare's CI: a turn ingested once,
-nothing stored before consent, deletions propagate, the name and kind follow the platform, recall over MCP carries the
-user and the conversation. Type checks there fail the build when this contract drifts from the service's schemas.
+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.
 
-## Hosts that cannot install the package yet
-Recordare is not published: `scripts/sync-to.sh <dir>` copies the sources 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. When Recordare is published the host switches to the npm package by changing its imports.
+## 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.
 
 ## Development
 `npm ci`, `npm run typecheck`, `npm test`, `npm run build` (Node ≥ 20).

package/README_it.md

@@ -2,28 +2,40 @@
 
 *Versione inglese (di riferimento): [README.md](README.md).*
 
-L'unica libreria client che ogni client di Recordare usa (WORK_PLAN 6.7): identità e consenso, impostazioni della
+> Da D50 (2026-10-09) Recordare non ha un flag di consenso: ogni memoria conserva ciò che il suo client invia;
+> l'interruttore acceso / spento appartiene alla piattaforma client (WORK_PLAN 8.1).
+
+L'unica libreria client che ogni client di Recordare usa (WORK_PLAN 6.7): identità, l'interruttore acceso / spento della piattaforma, impostazioni della
 persona, ingest, modifiche e cancellazioni, richiamo via MCP e la politica di consegna per l'outbox dell'host. È
 costruita sugli standard, così è l'host ad adattarsi: MCP con l'SDK ufficiale (streamable HTTP), errori come problem
 details RFC 9457, `Retry-After` (RFC 9110) rispettato, contesto di traccia W3C inoltrato, `fetch` nativo (l'host può
 passarne una sua, ad esempio con una politica sugli host in uscita). Nessun codice specifico di un host.
 
+Su npm da Recordare v0.1.0: `npm install @arkimedehq/recordare-client` (Node ≥ 20, modulo ES).
+
 ```ts
 import { PersonDirectory, RecordareClient, afterFailure } from '@arkimedehq/recordare-client';
 
 const rc = new RecordareClient({ baseUrl: 'http://recordare:8080', apiKey: process.env.RECORDARE_API_KEY!,
   headers: () => traceHeaders() });                       // es. propagation.inject di OpenTelemetry
 
-// Chi è l'utente, il suo consenso, il tipo di memoria e l'indirizzo di Atlas; il nome segue il profilo sulla piattaforma.
+// 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` è
+// 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' }) });
-await people.status('user-42');                           // 'active' | 'waiting_activation' | 'unknown'
+const person = await people.refresh('user-42');           // { memoryId, mode, atlasUrl }; peek() legge la cache
 
-// Ingest (diviso in richieste da 500, idempotente su ogni externalId). Prima del consenso non si conserva nulla.
+// Ingest (diviso in richieste da 500, idempotente su ogni externalId): → { conversationId, accepted, duplicates, conflicts }.
 await rc.ingest('user-42', { conversation: { externalId: 'chat-1' }, messages: [
   { externalId: 'm1', role: 'user', content: 'Domani vado a Bologna', sentAt: new Date().toISOString() },
 ] });
+// Il contenuto proprio dell'agente (conoscenza data, una percezione, un documento): `own: true` su un messaggio user / other.
+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() },
+] });
+// Modo (solo finché la memoria è vuota, altrimenti MemoryNotEmptyError) e genere della prima persona, dal profilo.
+await rc.updateMe('user-42', { gender: 'feminine' });
 
-// Richiamo: una sessione MCP per utente E conversazione (il contesto di chi vede), entrambi fissati nel codice.
+// 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
 const res = await rc.mcp.callTool('user-42', 'chat-1', 'search_episodes', { query: 'Bologna' });
 
@@ -31,6 +43,30 @@ const res = await rc.mcp.callTool('user-42', 'chat-1', 'search_episodes', { quer
 const next = afterFailure(err, attempts);                 // { action: 'retry', delayMs } | { action: 'park', reason }
 ```
 
+## Prima di ogni turno, e alla fine
+`contextWithTurn(user, turn)` salva il turno e restituisce il suo contesto di memoria in una sola andata e ritorno
+(`{block, items}`, il blocco da aggiungere in coda al prompt di sistema; `context(user, conversation, query)` quando il
+turno è già salvato); `endConversation(user, conversation)` dice a
+Recordare che una conversazione è finita (sessione chiusa, /new), così l'estrazione parte subito. `TOOLS` contiene gli
+schemi degli strumenti MCP che il servizio offre (nome, titolo, descrizione, JSON Schema), per gli host che devono
+dichiarare gli strumenti prima di collegarsi; la suite di conformità li tiene allineati al servizio.
+
+## Fonti apprese
+`learnSource(user, {externalId, title, text, kind?, author?, uri?, language?, learnedAt?, providedBy?, conversation?})`
+fa imparare un testo all'agente (D49, WORK_PLAN 8.9: un manuale, una pagina, una nota — **solo testo**, è l'host a
+convertire i file). Qualsiasi dimensione: un testo più grande di `SOURCE_PART_BYTES` (4 MB, o l'argomento `partBytes`)
+viene inviato a parti tagliate ai confini dei paragrafi (`POST api/v1/ingest/sources` + `…/parts`); → `{sourceId,
+status, parts, passages, duplicate}`. Lo stesso `externalId` sostituisce la fonte; `providedBy` è `'me'` (default),
+`'someone'` oppure `{name}`; `conversation: {externalId}` la collega alla conversazione in cui è stata imparata (è
+quell'estrazione a raccontare l'apprendimento). `forgetSource(user, externalId)` la dimentica (una mai inviata conta
+come fatto); `sources(user)` elenca ciò che l'agente ha imparato (`Source[]`). L'agente la cerca con lo strumento MCP
+`search_knowledge`. Inviare solo ciò che l'agente deve imparare, mai i risultati di ricerca di un RAG.
+
+```ts
+await rc.learnSource('user-42', { externalId: 'boiler-manual', title: 'Manuale della caldaia', text: manualText,
+  kind: 'document', providedBy: { name: 'Paolo' }, conversation: { externalId: 'chat-1' } });
+```
+
 ## 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
@@ -42,14 +78,14 @@ ingest. Tutto il resto è qui, uguale per ogni client.
 
 ## Conformità
 `service/test/conformance` esegue questa libreria contro il servizio vero nella CI di Recordare: un turno salvato una
-volta sola, nulla conservato prima del consenso, le cancellazioni si propagano, nome e tipo seguono la piattaforma, il
-richiamo via MCP porta l'utente e la conversazione. I controlli di tipo lì fanno fallire la build se questo contratto si
+volta sola, le cancellazioni si propagano, nome, modo e genere seguono la piattaforma, il contenuto proprio è marcato, una
+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.
 
-## Host che non possono ancora installare il pacchetto
-Recordare non è pubblicato: `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. Quando Recordare sarà pubblicato l'host passerà al pacchetto npm cambiando solo
+## 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.
 
 ## Sviluppo

package/dist/client.d.ts

@@ -1,8 +1,8 @@
-import { type Digest, type Episode, type EpisodeDetail, type EpisodeQuery, type Fact, type IngestRequest, type IngestResult, type Me, type MeSettings, type MemoryContext, type Note, type PlanStatus, type Precision } from './contract.js';
+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 ClientOptions, Http } from './http.js';
 import { RecordareMcp, type McpOptions } from './mcp.js';
 /**
- * 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`).
  */
@@ -12,13 +12,13 @@ export declare class RecordareClient {
     constructor(options: ClientOptions & {
         mcp?: McpOptions;
     });
-    /** 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>;
-    /** 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. */
     updateMe(user: string, settings: MeSettings): 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. 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.
      */
     ingest(user: string, req: IngestRequest): Promise<IngestResult>;
     /**
@@ -27,12 +27,28 @@ export declare class RecordareClient {
      * caching); never store it as a chat message.
      */
     context(user: string, conversation: string, query: string): 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>;
+    /** 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. */
     editMessage(user: string, conversation: string, message: string, content: string): Promise<void>;
     /** A deleted message: Recordare forgets it and what came only from it. A message it never had counts as done. */
     deleteMessage(user: string, conversation: string, message: string): Promise<void>;
     /** A deleted conversation. A conversation Recordare never had counts as done. */
     deleteConversation(user: string, conversation: string): Promise<void>;
+    /**
+     * 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.
+     */
+    learnSource(user: string, source: LearnSource, partBytes?: number): Promise<LearnSourceResult>;
+    /** The agent forgets a source (its text and passages; episodes keep a "forgotten source" marker). One it never had counts as done. */
+    forgetSource(user: string, externalId: string): Promise<void>;
+    /** What the agent learned, newest first. */
+    sources(user: string): Promise<Source[]>;
     /** The timeline, newest first; pass `nextCursor` back as `cursor` for the next page. */
     episodes(user: string, query?: EpisodeQuery): Promise<{
         items: Episode[];
@@ -75,3 +91,5 @@ export declare class RecordareClient {
     close(): Promise<void>;
     private gone;
 }
+/** 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 declare function splitParts(text: string, maxBytes: number): string[];

package/dist/client.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 // Copyright © 2026 Andrea Genovese
-import { CONVERSATION_HEADER, MAX_MESSAGES_PER_REQUEST, } from './contract.js';
+import { CONVERSATION_HEADER, MAX_MESSAGES_PER_REQUEST, SOURCE_PART_BYTES, } from './contract.js';
 import { MemoryNotEmptyError, RecordareHttpError } from './errors.js';
 import { Http } from './http.js';
 import { RecordareMcp } from './mcp.js';
@@ -15,7 +15,7 @@ function qs(query) {
     return s ? `?${s}` : '';
 }
 /**
- * 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`).
  */
@@ -26,11 +26,11 @@ export class RecordareClient {
         this.http = new Http(options);
         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) {
         return this.http.request('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, settings) {
         try {
             await this.http.request('PATCH', 'api/v1/me', { user, body: settings });
@@ -43,10 +43,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, req) {
-        const total = { conversationId: null, accepted: 0, duplicates: 0, conflicts: [], stored: true };
+        const total = { 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('POST', 'api/v1/ingest/messages', {
@@ -62,7 +62,6 @@ export class RecordareClient {
             total.accepted += part.accepted;
             total.duplicates += part.duplicates;
             total.conflicts.push(...part.conflicts);
-            total.stored &&= part.stored;
         }
         return total;
     }
@@ -74,6 +73,17 @@ export class RecordareClient {
     context(user, conversation, query) {
         return this.http.request('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, turn, query) {
+        return this.http.request('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, conversation) {
+        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, conversation, message, content) {
         await this.http.request('PATCH', `api/v1/ingest/conversations/${enc(conversation)}/messages/${enc(message)}`, { user, body: { content } });
@@ -86,6 +96,29 @@ export class RecordareClient {
     async deleteConversation(user, conversation) {
         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, source, partBytes = SOURCE_PART_BYTES) {
+        const [first = '', ...rest] = splitParts(source.text, partBytes);
+        let result = await this.http.request('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('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, externalId) {
+        await this.http.request('DELETE', `api/v1/ingest/sources/${enc(externalId)}`, { user });
+    }
+    /** What the agent learned, newest first. */
+    sources(user) {
+        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. */
     episodes(user, query = {}) {
@@ -140,3 +173,40 @@ 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, maxBytes) {
+    const size = (t) => Buffer.byteLength(t, 'utf8');
+    if (size(text) <= maxBytes)
+        return [text];
+    const parts = [];
+    let current = '';
+    const push = (piece) => {
+        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/dist/contract.d.ts

@@ -5,21 +5,25 @@
  */
 /** The client's user the request acts for (with a client key). */
 export declare 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 declare const CONVERSATION_HEADER = "X-Recordare-Conversation";
 /** Largest message content Recordare accepts (UTF-8 bytes). */
 export declare const MAX_CONTENT_BYTES: number;
 /** Largest number of messages in one ingest request. */
 export declare 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;
@@ -30,7 +34,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;
@@ -41,13 +47,19 @@ export type ParticipantIdentity = {
 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. */
     externalId: string;
@@ -69,6 +81,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 {
     conversation: IngestConversation;
@@ -79,12 +93,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;
 }
 export type PlanStatus = 'open' | 'confirmed' | 'cancelled' | 'rescheduled' | 'unresolved';
 export type Precision = 'minute' | 'day' | 'month' | 'year' | 'approximate' | 'unknown';
@@ -184,9 +197,61 @@ export interface Note {
     supportCount: number;
     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 declare const SOURCE_PART_BYTES: number;
+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/dist/contract.js

@@ -7,12 +7,14 @@
  */
 /** 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). */
 export const MAX_CONTENT_BYTES = 64 * 1024;
 /** Largest number of messages in one ingest request. */
 export const MAX_MESSAGES_PER_REQUEST = 500;
+/** 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;
 /**
  * Cuts text to at most `maxBytes` UTF-8 bytes without splitting a character, ending with `marker` so a reader (and the
  * memory engine) knows the text was cut. The marker counts within the limit.

package/dist/errors.d.ts

@@ -21,7 +21,7 @@ export declare class RecordareHttpError extends Error {
 export declare class RecordareUnavailableError extends Error {
     constructor(message: string, cause?: unknown);
 }
-/** 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 declare class MemoryNotEmptyError extends Error {
     constructor();
 }

package/dist/errors.js

@@ -23,10 +23,10 @@ export class RecordareUnavailableError extends Error {
         this.name = 'RecordareUnavailableError';
     }
 }
-/** 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/dist/index.d.ts

@@ -4,5 +4,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/dist/index.js

@@ -7,4 +7,5 @@ export { parseRetryAfter } from './http.js';
 export { RecordareClient } from './client.js';
 export { RecordareMcp } from './mcp.js';
 export { PersonDirectory } from './people.js';
+export { TOOLS } from './tools.js';
 export { afterFailure, backoffMs, DEFAULT_DELIVERY } from './delivery.js';

package/dist/mcp.js

@@ -1,8 +1,8 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 // 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.
  */
@@ -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.1.0' });
+        const client = new Client(this.options.clientInfo ?? { name: 'recordare-client', version: '0.2.0' });
         await client.connect(transport);
         return client;
     }