@arkimedehq/recordare-client 0.1.0 → 0.2.0

package/dist/people.d.ts

@@ -1,17 +1,15 @@
 /**
- * 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;
 }
 /** The user as the platform knows them. */
@@ -26,7 +24,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;
@@ -40,13 +38,9 @@ export declare class PersonDirectory {
     /** Last known person (possibly stale), or undefined; a stale or missing entry is refreshed in the background. */
     peek(user: string): Person | undefined;
     /** 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;
+    seed(user: string, memoryId: string): void;
     /** Forgets a user (e.g. after their switch or name changed): the next read asks Recordare again. */
     invalidate(user: string): void;
-    /** Users whose consent is known to be off: a sender skips them (nothing is buffered before consent). */
-    knownOff(): string[];
-    /** Re-checks now, waiting at most `timeoutMs`; falls back to the last known state. */
-    status(user: string, timeoutMs?: number): Promise<ConsentState>;
     /** Asks Recordare now (one request in flight per user). */
     refresh(user: string): Promise<Person>;
     private lookup;

package/dist/people.js

@@ -20,30 +20,14 @@ export class PersonDirectory {
         return person;
     }
     /** 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, ownerId) {
+    seed(user, memoryId) {
         if (!this.cache.has(user))
-            this.cache.set(user, { ownerId, consent: null, kind: null, atlasUrl: null, until: 0 });
+            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. */
     invalidate(user) {
         this.cache.delete(user);
     }
-    /** Users whose consent is known to be off: a sender skips them (nothing is buffered before consent). */
-    knownOff() {
-        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, timeoutMs = 3_000) {
-        let timer;
-        const fresh = await Promise.race([
-            this.refresh(user).catch(() => undefined),
-            new Promise((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) {
         const running = this.inflight.get(user);
@@ -64,19 +48,19 @@ export class PersonDirectory {
             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 });
+                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 = { ownerId: me.ownerId, consent: me.episodicEnabled, kind: me.kind, atlasUrl: me.atlasUrl ?? null };
+            const 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 });
         }
     }
 }

package/dist/tools.d.ts

@@ -0,0 +1,226 @@
+/**
+ * The MCP tools Recordare serves (name, title, description, JSON Schema of the arguments), for connectors that must
+ * declare tools before talking to the service. Generated by the conformance suite (service/test/conformance,
+ * RECORDARE_UPDATE_TOOLS=1), which fails when this copy drifts from the service.
+ */
+export declare const TOOLS: readonly [{
+    readonly name: "correct_episode";
+    readonly title: "Correct a memory";
+    readonly description: "Correct a remembered episode (wrong date or detail). The old version is kept as history, never shown as current.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly id: {
+                readonly type: "string";
+                readonly format: "uuid";
+                readonly pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$";
+            };
+            readonly content: {
+                readonly type: "string";
+            };
+            readonly occurred_at: {
+                readonly type: "string";
+                readonly pattern: "^\\d{4}-\\d{2}(-\\d{2})?$";
+            };
+            readonly date_precision: {
+                readonly type: "string";
+                readonly enum: readonly ["day", "month", "year", "approximate"];
+            };
+        };
+        readonly required: readonly ["id"];
+        readonly $schema: "http://json-schema.org/draft-07/schema#";
+    };
+}, {
+    readonly name: "forget_episode";
+    readonly title: "Forget a memory";
+    readonly description: "Forget an episode, when asked to. It is deleted with its corrections and never recreated.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly id: {
+                readonly type: "string";
+                readonly format: "uuid";
+                readonly pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$";
+            };
+        };
+        readonly required: readonly ["id"];
+        readonly $schema: "http://json-schema.org/draft-07/schema#";
+    };
+}, {
+    readonly name: "learn_source";
+    readonly title: "Learn a text";
+    readonly description: "Learn a text as knowledge (a manual, a page, a note — as plain text; send it again with the same title to replace it). It stays searchable with search_knowledge; the learning becomes a memory of this conversation.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly title: {
+                readonly type: "string";
+            };
+            readonly text: {
+                readonly type: "string";
+            };
+            readonly author: {
+                readonly type: "string";
+            };
+            readonly kind: {
+                readonly type: "string";
+                readonly enum: readonly ["document", "page", "note", "book", "own_text"];
+            };
+            readonly uri: {
+                readonly type: "string";
+            };
+        };
+        readonly required: readonly ["title", "text"];
+        readonly $schema: "http://json-schema.org/draft-07/schema#";
+    };
+}, {
+    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 inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly content: {
+                readonly type: "string";
+            };
+            readonly kind: {
+                readonly type: "string";
+                readonly enum: readonly ["event", "plan"];
+            };
+            readonly occurred_at: {
+                readonly type: "string";
+                readonly pattern: "^\\d{4}-\\d{2}(-\\d{2})?$";
+            };
+            readonly occurred_until: {
+                readonly type: "string";
+                readonly pattern: "^\\d{4}-\\d{2}(-\\d{2})?$";
+            };
+            readonly date_precision: {
+                readonly type: "string";
+                readonly enum: readonly ["day", "month", "year", "approximate"];
+            };
+            readonly people: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+            readonly place: {
+                readonly type: "string";
+            };
+        };
+        readonly required: readonly ["content"];
+        readonly $schema: "http://json-schema.org/draft-07/schema#";
+    };
+}, {
+    readonly name: "remember";
+    readonly title: "Remember something";
+    readonly description: "Explicit \"remember that…\" about preferences, habits, values, knowledge.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly content: {
+                readonly type: "string";
+            };
+            readonly category: {
+                readonly type: "string";
+                readonly enum: readonly ["preference", "habit", "value", "relationship", "knowledge", "profile", "constraint"];
+            };
+        };
+        readonly required: readonly ["content"];
+        readonly $schema: "http://json-schema.org/draft-07/schema#";
+    };
+}, {
+    readonly name: "resolve_period";
+    readonly title: "Turn a period expression into dates";
+    readonly description: "Deterministic: \"questa settimana\", \"la settimana scorsa\", \"a febbraio\", \"lo scorso dicembre\", \"last week\"… → {from, to} (ISO, inclusive).";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly expression: {
+                readonly type: "string";
+            };
+        };
+        readonly required: readonly ["expression"];
+        readonly $schema: "http://json-schema.org/draft-07/schema#";
+    };
+}, {
+    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 inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly query: {
+                readonly description: "What to look for — pass the question also when listing a period: it ranks the items and finds the matching chat excerpts";
+                readonly type: "string";
+            };
+            readonly from: {
+                readonly description: "Start date, ISO (YYYY-MM-DD or YYYY-MM)";
+                readonly type: "string";
+                readonly pattern: "^\\d{4}-\\d{2}(-\\d{2})?$";
+            };
+            readonly to: {
+                readonly description: "End date, ISO (YYYY-MM-DD or YYYY-MM), inclusive";
+                readonly type: "string";
+                readonly pattern: "^\\d{4}-\\d{2}(-\\d{2})?$";
+            };
+            readonly mode: {
+                readonly type: "string";
+                readonly enum: readonly ["search", "list", "latest"];
+            };
+            readonly include_plans: {
+                readonly type: "boolean";
+            };
+            readonly limit: {
+                readonly type: "integer";
+                readonly minimum: 1;
+                readonly maximum: 50;
+            };
+        };
+        readonly $schema: "http://json-schema.org/draft-07/schema#";
+    };
+}, {
+    readonly name: "search_knowledge";
+    readonly title: "Search what you learned";
+    readonly description: "Search the sources you learned (manuals, documents, pages, notes you were given or wrote): passages of their text, each with its source (title, author, who gave it, when) and the episodes that refer to it. For what happened, use search_episodes.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly query: {
+                readonly type: "string";
+                readonly description: "What to look up";
+            };
+            readonly limit: {
+                readonly type: "integer";
+                readonly minimum: 1;
+                readonly maximum: 20;
+            };
+        };
+        readonly required: readonly ["query"];
+        readonly $schema: "http://json-schema.org/draft-07/schema#";
+    };
+}, {
+    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 inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly query: {
+                readonly type: "string";
+                readonly description: "Topic";
+            };
+            readonly as_of: {
+                readonly description: "ISO date (YYYY-MM-DD); default today";
+                readonly type: "string";
+                readonly pattern: "^\\d{4}-\\d{2}(-\\d{2})?$";
+            };
+            readonly include_pending: {
+                readonly type: "boolean";
+            };
+        };
+        readonly required: readonly ["query"];
+        readonly $schema: "http://json-schema.org/draft-07/schema#";
+    };
+}];

package/dist/tools.js

@@ -0,0 +1,286 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright © 2026 Andrea Genovese
+/**
+ * The MCP tools Recordare serves (name, title, description, JSON Schema of the arguments), for connectors that must
+ * declare tools before talking to the service. Generated by the conformance suite (service/test/conformance,
+ * RECORDARE_UPDATE_TOOLS=1), which fails when this copy drifts from the service.
+ */
+export const TOOLS = [
+    {
+        "name": "correct_episode",
+        "title": "Correct a memory",
+        "description": "Correct a remembered episode (wrong date or detail). The old version is kept as history, never shown as current.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "format": "uuid",
+                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+                },
+                "content": {
+                    "type": "string"
+                },
+                "occurred_at": {
+                    "type": "string",
+                    "pattern": "^\\d{4}-\\d{2}(-\\d{2})?$"
+                },
+                "date_precision": {
+                    "type": "string",
+                    "enum": [
+                        "day",
+                        "month",
+                        "year",
+                        "approximate"
+                    ]
+                }
+            },
+            "required": [
+                "id"
+            ],
+            "$schema": "http://json-schema.org/draft-07/schema#"
+        }
+    },
+    {
+        "name": "forget_episode",
+        "title": "Forget a memory",
+        "description": "Forget an episode, when asked to. It is deleted with its corrections and never recreated.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "format": "uuid",
+                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+                }
+            },
+            "required": [
+                "id"
+            ],
+            "$schema": "http://json-schema.org/draft-07/schema#"
+        }
+    },
+    {
+        "name": "learn_source",
+        "title": "Learn a text",
+        "description": "Learn a text as knowledge (a manual, a page, a note — as plain text; send it again with the same title to replace it). It stays searchable with search_knowledge; the learning becomes a memory of this conversation.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "title": {
+                    "type": "string"
+                },
+                "text": {
+                    "type": "string"
+                },
+                "author": {
+                    "type": "string"
+                },
+                "kind": {
+                    "type": "string",
+                    "enum": [
+                        "document",
+                        "page",
+                        "note",
+                        "book",
+                        "own_text"
+                    ]
+                },
+                "uri": {
+                    "type": "string"
+                }
+            },
+            "required": [
+                "title",
+                "text"
+            ],
+            "$schema": "http://json-schema.org/draft-07/schema#"
+        }
+    },
+    {
+        "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).",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "content": {
+                    "type": "string"
+                },
+                "kind": {
+                    "type": "string",
+                    "enum": [
+                        "event",
+                        "plan"
+                    ]
+                },
+                "occurred_at": {
+                    "type": "string",
+                    "pattern": "^\\d{4}-\\d{2}(-\\d{2})?$"
+                },
+                "occurred_until": {
+                    "type": "string",
+                    "pattern": "^\\d{4}-\\d{2}(-\\d{2})?$"
+                },
+                "date_precision": {
+                    "type": "string",
+                    "enum": [
+                        "day",
+                        "month",
+                        "year",
+                        "approximate"
+                    ]
+                },
+                "people": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "place": {
+                    "type": "string"
+                }
+            },
+            "required": [
+                "content"
+            ],
+            "$schema": "http://json-schema.org/draft-07/schema#"
+        }
+    },
+    {
+        "name": "remember",
+        "title": "Remember something",
+        "description": "Explicit \"remember that…\" about preferences, habits, values, knowledge.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "content": {
+                    "type": "string"
+                },
+                "category": {
+                    "type": "string",
+                    "enum": [
+                        "preference",
+                        "habit",
+                        "value",
+                        "relationship",
+                        "knowledge",
+                        "profile",
+                        "constraint"
+                    ]
+                }
+            },
+            "required": [
+                "content"
+            ],
+            "$schema": "http://json-schema.org/draft-07/schema#"
+        }
+    },
+    {
+        "name": "resolve_period",
+        "title": "Turn a period expression into dates",
+        "description": "Deterministic: \"questa settimana\", \"la settimana scorsa\", \"a febbraio\", \"lo scorso dicembre\", \"last week\"… → {from, to} (ISO, inclusive).",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "expression": {
+                    "type": "string"
+                }
+            },
+            "required": [
+                "expression"
+            ],
+            "$schema": "http://json-schema.org/draft-07/schema#"
+        }
+    },
+    {
+        "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…\").",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "description": "What to look for — pass the question also when listing a period: it ranks the items and finds the matching chat excerpts",
+                    "type": "string"
+                },
+                "from": {
+                    "description": "Start date, ISO (YYYY-MM-DD or YYYY-MM)",
+                    "type": "string",
+                    "pattern": "^\\d{4}-\\d{2}(-\\d{2})?$"
+                },
+                "to": {
+                    "description": "End date, ISO (YYYY-MM-DD or YYYY-MM), inclusive",
+                    "type": "string",
+                    "pattern": "^\\d{4}-\\d{2}(-\\d{2})?$"
+                },
+                "mode": {
+                    "type": "string",
+                    "enum": [
+                        "search",
+                        "list",
+                        "latest"
+                    ]
+                },
+                "include_plans": {
+                    "type": "boolean"
+                },
+                "limit": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 50
+                }
+            },
+            "$schema": "http://json-schema.org/draft-07/schema#"
+        }
+    },
+    {
+        "name": "search_knowledge",
+        "title": "Search what you learned",
+        "description": "Search the sources you learned (manuals, documents, pages, notes you were given or wrote): passages of their text, each with its source (title, author, who gave it, when) and the episodes that refer to it. For what happened, use search_episodes.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "What to look up"
+                },
+                "limit": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 20
+                }
+            },
+            "required": [
+                "query"
+            ],
+            "$schema": "http://json-schema.org/draft-07/schema#"
+        }
+    },
+    {
+        "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.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "Topic"
+                },
+                "as_of": {
+                    "description": "ISO date (YYYY-MM-DD); default today",
+                    "type": "string",
+                    "pattern": "^\\d{4}-\\d{2}(-\\d{2})?$"
+                },
+                "include_pending": {
+                    "type": "boolean"
+                }
+            },
+            "required": [
+                "query"
+            ],
+            "$schema": "http://json-schema.org/draft-07/schema#"
+        }
+    }
+];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@arkimedehq/recordare-client",
-  "version": "0.1.0",
-  "description": "Client library for Recordare, the memory service for agent platforms: identity, consent, ingest, deletions, MCP recall.",
+  "version": "0.2.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",
   "homepage": "https://github.com/arkimedehq/recordare/tree/main/packages/client#readme",