@hexis-ai/engram-sdk 0.16.0 → 0.17.0

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 import type { ScoredSession, SearchOptions, Session, SessionStep } from "@hexis-ai/engram-core";
 import { type RefCandidate } from "./extract";
-import type { AliasInfo, AliasUpsert, EventBatch, IdentityInfo, IdentityUpsert, MessageContentBlock, PersonCreate, PersonInfo, PersonMap, PersonUpdate, SessionEvent, SessionInit, SessionUpdate } from "./types";
+import type { AliasInfo, AliasUpsert, EventBatch, IdentityInfo, IdentityUpsert, MessageContentBlock, PersonCreate, PersonInfo, PersonMap, PersonMemory, PersonMemoryCreate, PersonUpdate, SessionEvent, SessionInit, SessionUpdate } from "./types";
 import { type TelemetryAlias, type TelemetryEvent, type TelemetryIdentity, type TelemetryMessage, type TelemetryPerson, type TelemetrySession } from "./buffered";
 /**
  * Envelope returned by session endpoints. The persons map is deduped
@@ -205,6 +205,12 @@ export declare class Engram {
         upsert: (id: string, input: PersonCreate) => Promise<PersonInfo>;
         /** Patch profile fields. Returns 404 if id is unknown. */
         update: (id: string, patch: PersonUpdate) => Promise<PersonInfo>;
+        /**
+         * Hard-delete a person; cascades to aliases / identities / memories.
+         * Throws on 404 when the id is unknown — callers that want
+         * idempotent semantics should catch and ignore.
+         */
+        delete: (id: string) => Promise<void>;
         get: (id: string) => Promise<PersonInfo>;
         /** Free-text search (substring across id + display_name). */
         list: (opts?: {
@@ -224,6 +230,12 @@ export declare class Engram {
          * case-insensitive — writing `Yuuri` and `YUURI` hits the same row.
          */
         upsertAlias: (id: string, name: string, input: AliasUpsert) => Promise<AliasInfo>;
+        /**
+         * Remove an alias by (person, name). Name match is
+         * case-insensitive, mirroring the upsert key. 404s when the alias
+         * isn't there — catch and ignore for idempotent cleanup.
+         */
+        removeAlias: (id: string, name: string) => Promise<void>;
         /** This person's aliases, newest-used-first. */
         aliases: (id: string) => Promise<{
             aliases: AliasInfo[];
@@ -232,6 +244,31 @@ export declare class Engram {
         identities: (id: string) => Promise<{
             identities: IdentityInfo[];
         }>;
+        /**
+         * Per-person memory surface — the ChatGPT/Claude-style "things to
+         * remember about this person". Reads are hot path (the host agent
+         * pulls every participant's memories on each turn) so the server
+         * keeps `(workspace, person, created_at DESC)` indexed; writes are
+         * ack'd synchronously, unlike the fire-and-forget telemetry calls.
+         */
+        memories: {
+            /** Newest-first; honours `?limit=` server-side. */
+            list: (id: string, opts?: {
+                limit?: number;
+            }) => Promise<{
+                memories: PersonMemory[];
+            }>;
+            /**
+             * Append a memory. Returns the stored row (with allocated `id`)
+             * so callers that want to immediately echo "saved: <content>"
+             * back to the user don't have to re-fetch. Throws on 404 when
+             * the person doesn't exist.
+             */
+            add: (id: string, input: PersonMemoryCreate) => Promise<PersonMemory>;
+            /** Remove by memory id. Idempotent — second call 404s, callers
+             *  can choose to ignore. */
+            remove: (id: string, memoryId: string) => Promise<void>;
+        };
     };
     /** Identity operations — resolve a global ref (`slack:U…`, `email:…`)
      *  to its identity record + person id. */

package/dist/client.js

@@ -191,6 +191,12 @@ export class Engram {
         upsert: (id, input) => this.request("PUT", `/v1/persons/${encodeURIComponent(id)}`, input),
         /** Patch profile fields. Returns 404 if id is unknown. */
         update: (id, patch) => this.request("PATCH", `/v1/persons/${encodeURIComponent(id)}`, patch),
+        /**
+         * Hard-delete a person; cascades to aliases / identities / memories.
+         * Throws on 404 when the id is unknown — callers that want
+         * idempotent semantics should catch and ignore.
+         */
+        delete: (id) => this.request("DELETE", `/v1/persons/${encodeURIComponent(id)}`),
         get: (id) => this.request("GET", `/v1/persons/${encodeURIComponent(id)}`),
         /** Free-text search (substring across id + display_name). */
         list: (opts = {}) => {
@@ -219,10 +225,43 @@ export class Engram {
          * case-insensitive — writing `Yuuri` and `YUURI` hits the same row.
          */
         upsertAlias: (id, name, input) => this.request("PUT", `/v1/persons/${encodeURIComponent(id)}/aliases/${encodeURIComponent(name)}`, input),
+        /**
+         * Remove an alias by (person, name). Name match is
+         * case-insensitive, mirroring the upsert key. 404s when the alias
+         * isn't there — catch and ignore for idempotent cleanup.
+         */
+        removeAlias: (id, name) => this.request("DELETE", `/v1/persons/${encodeURIComponent(id)}/aliases/${encodeURIComponent(name)}`),
         /** This person's aliases, newest-used-first. */
         aliases: (id) => this.request("GET", `/v1/persons/${encodeURIComponent(id)}/aliases`),
         /** This person's identities, newest-linked-first. */
         identities: (id) => this.request("GET", `/v1/persons/${encodeURIComponent(id)}/identities`),
+        /**
+         * Per-person memory surface — the ChatGPT/Claude-style "things to
+         * remember about this person". Reads are hot path (the host agent
+         * pulls every participant's memories on each turn) so the server
+         * keeps `(workspace, person, created_at DESC)` indexed; writes are
+         * ack'd synchronously, unlike the fire-and-forget telemetry calls.
+         */
+        memories: {
+            /** Newest-first; honours `?limit=` server-side. */
+            list: (id, opts = {}) => {
+                const qs = new URLSearchParams();
+                if (opts.limit !== undefined)
+                    qs.set("limit", String(opts.limit));
+                const tail = qs.toString();
+                return this.request("GET", `/v1/persons/${encodeURIComponent(id)}/memories${tail ? `?${tail}` : ""}`);
+            },
+            /**
+             * Append a memory. Returns the stored row (with allocated `id`)
+             * so callers that want to immediately echo "saved: <content>"
+             * back to the user don't have to re-fetch. Throws on 404 when
+             * the person doesn't exist.
+             */
+            add: (id, input) => this.request("POST", `/v1/persons/${encodeURIComponent(id)}/memories`, input),
+            /** Remove by memory id. Idempotent — second call 404s, callers
+             *  can choose to ignore. */
+            remove: (id, memoryId) => this.request("DELETE", `/v1/persons/${encodeURIComponent(id)}/memories/${encodeURIComponent(memoryId)}`),
+        },
     };
     /** Identity operations — resolve a global ref (`slack:U…`, `email:…`)
      *  to its identity record + person id. */

package/dist/index.d.ts

@@ -4,4 +4,4 @@ export { parseToolName, type ParsedToolName } from "./tool-name";
 export { BufferedTelemetry, type TelemetrySession, type TelemetryMessage, type TelemetryEvent, type TelemetryPerson, type TelemetryIdentity, type TelemetryAlias, } from "./buffered";
 export { fetchIdToken, cloudRunIdTokenAuth } from "./id-token";
 export { EngramAdmin, createAdminClient, type AdminClientOptions, type CreateWorkspaceInput, type CreateWorkspaceResult, type Workspace as AdminWorkspace, type ApiKey as AdminApiKey, type IssuedKey as AdminIssuedKey, type Org, type OrgMembership, type CreateOrgInput, type UpsertMemberInput, type OrgWorkspace, } from "./admin";
-export type { SessionInit, SessionUpdate, SessionAck, SessionEvent, StepEvent, ParticipantEvent, TitleEvent, EndEvent, MessageContentBlock, MessageEvent, EventBatch, PersonInfo, PersonCreate, PersonUpdate, PersonMap, AliasInfo, AliasUpsert, IdentityInfo, IdentityUpsert, } from "./types";
+export type { SessionInit, SessionUpdate, SessionAck, SessionEvent, StepEvent, ParticipantEvent, TitleEvent, EndEvent, MessageContentBlock, MessageEvent, EventBatch, PersonInfo, PersonCreate, PersonUpdate, PersonMap, AliasInfo, AliasUpsert, IdentityInfo, IdentityUpsert, PersonMemory, PersonMemoryCreate, } from "./types";

package/dist/types.d.ts

@@ -264,6 +264,37 @@ export interface IdentityUpsert {
      */
     unlinked_at?: string | null;
 }
+/**
+ * One free-form fact about a person — the building block of the
+ * ChatGPT/Claude-style "memory" surface. The host agent loads a
+ * person's recent memories into context at conversation start and
+ * appends new ones (via `save_person_memory`) as it learns. Content
+ * is intentionally unstructured: representing a fact like "prefers
+ * morning meetings" as plain text keeps the surface symmetric with
+ * how an LLM thinks about a person.
+ */
+export interface PersonMemory {
+    id: string;
+    person_id: string;
+    content: string;
+    /**
+     * Where the memory came from:
+     *   - `agent`   — saved by the LLM via the host's save tool.
+     *   - `manual`  — entered by a human via the engram-web UI.
+     *   - `auto`    — derived by a downstream pipeline.
+     * Server-side defaults to `agent` when omitted.
+     */
+    source: string;
+    /** Session the memory was extracted from, when the writer knew one. */
+    source_session_id: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface PersonMemoryCreate {
+    content: string;
+    source?: string;
+    source_session_id?: string | null;
+}
 /**
  * Map of person_id → PersonInfo, deduped across whatever `Session`s the
  * response contains. Returned at the envelope level so list responses

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hexis-ai/engram-sdk",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "author": "hexis ltd.",
   "repository": {
     "type": "git",