@hexis-ai/engram-server 0.16.0 → 0.17.0

package/dist/adapters/memory.d.ts

@@ -1,9 +1,11 @@
 import type { Session } from "@hexis-ai/engram-core";
-import type { AliasInfo, AliasUpsert, IdentityInfo, IdentityUpsert, PersonCreate, PersonInfo, PersonUpdate, SessionEvent, SessionInit, SessionUpdate } from "@hexis-ai/engram-sdk";
+import type { AliasInfo, AliasUpsert, IdentityInfo, IdentityUpsert, PersonCreate, PersonInfo, PersonMemory, PersonMemoryCreate, PersonUpdate, SessionEvent, SessionInit, SessionUpdate } from "@hexis-ai/engram-sdk";
 import { type StorageAdapter } from "../storage";
 export interface InMemoryAdapterOptions {
     /** Override for tests. Default: `p_${random}` with 8 chars. */
     newPersonId?: () => string;
+    /** Override for tests. Default: `mem_${random}` with 12 chars. */
+    newMemoryId?: () => string;
 }
 /**
  * In-process storage adapter for tests, dev, and small single-node deploys.
@@ -16,7 +18,10 @@ export declare class InMemoryAdapter implements StorageAdapter {
     private readonly aliases;
     /** Keyed by ref (e.g. `slack:U12345`). */
     private readonly identities;
+    /** Keyed by memory id. */
+    private readonly memories;
     private readonly newPersonId;
+    private readonly newMemoryId;
     constructor(opts?: InMemoryAdapterOptions);
     createSession(init: SessionInit & {
         id: string;
@@ -43,6 +48,7 @@ export declare class InMemoryAdapter implements StorageAdapter {
     createPerson(input: PersonCreate): Promise<PersonInfo>;
     upsertPerson(id: string, input: PersonCreate): Promise<PersonInfo>;
     updatePerson(id: string, patch: PersonUpdate): Promise<PersonInfo | null>;
+    deletePerson(id: string): Promise<boolean>;
     getPerson(id: string): Promise<PersonInfo | null>;
     getPersons(ids: string[]): Promise<PersonInfo[]>;
     listPersons(opts: {
@@ -53,8 +59,14 @@ export declare class InMemoryAdapter implements StorageAdapter {
         name: string;
     } & AliasUpsert): Promise<AliasInfo | null>;
     listAliases(personId: string): Promise<AliasInfo[]>;
+    deleteAlias(personId: string, name: string): Promise<boolean>;
     findAliasesByName(name: string): Promise<AliasInfo[]>;
     upsertIdentity(ref: string, input: IdentityUpsert): Promise<IdentityInfo | null>;
     getIdentityByRef(ref: string): Promise<IdentityInfo | null>;
     listIdentitiesByPerson(personId: string): Promise<IdentityInfo[]>;
+    addPersonMemory(personId: string, input: PersonMemoryCreate): Promise<PersonMemory | null>;
+    listPersonMemories(personId: string, opts: {
+        limit: number;
+    }): Promise<PersonMemory[]>;
+    deletePersonMemory(memoryId: string): Promise<boolean>;
 }

package/dist/adapters/memory.js

@@ -1,4 +1,4 @@
-import { foldEvents, newPersonId } from "../storage";
+import { foldEvents, newPersonId, newPersonMemoryId, } from "../storage";
 import { applyPartial } from "./util";
 /**
  * In-process storage adapter for tests, dev, and small single-node deploys.
@@ -11,9 +11,13 @@ export class InMemoryAdapter {
     aliases = new Map();
     /** Keyed by ref (e.g. `slack:U12345`). */
     identities = new Map();
+    /** Keyed by memory id. */
+    memories = new Map();
     newPersonId;
+    newMemoryId;
     constructor(opts = {}) {
         this.newPersonId = opts.newPersonId ?? newPersonId;
+        this.newMemoryId = opts.newMemoryId ?? newPersonMemoryId;
     }
     // --- Sessions -----------------------------------------------------
     async createSession(init) {
@@ -188,6 +192,27 @@ export class InMemoryAdapter {
         this.persons.set(id, next);
         return next;
     }
+    async deletePerson(id) {
+        if (!this.persons.has(id))
+            return false;
+        this.persons.delete(id);
+        // Mirror the postgres FK cascade so behaviour is symmetric:
+        // dependent aliases / identities / memories vanish with the
+        // person.
+        for (const [key, alias] of this.aliases) {
+            if (alias.person_id === id)
+                this.aliases.delete(key);
+        }
+        for (const [ref, identity] of this.identities) {
+            if (identity.person_id === id)
+                this.identities.delete(ref);
+        }
+        for (const [memId, memory] of this.memories) {
+            if (memory.person_id === id)
+                this.memories.delete(memId);
+        }
+        return true;
+    }
     async getPerson(id) {
         return this.persons.get(id) ?? null;
     }
@@ -268,6 +293,9 @@ export class InMemoryAdapter {
         matches.sort((a, b) => b.last_used.localeCompare(a.last_used));
         return matches;
     }
+    async deleteAlias(personId, name) {
+        return this.aliases.delete(aliasKey(personId, name));
+    }
     async findAliasesByName(name) {
         const lower = name.toLowerCase();
         const matches = [...this.aliases.values()].filter((a) => a.name.toLowerCase() === lower);
@@ -328,6 +356,31 @@ export class InMemoryAdapter {
         matches.sort((a, b) => b.linked_at.localeCompare(a.linked_at));
         return matches;
     }
+    // --- Person memories ---------------------------------------------
+    async addPersonMemory(personId, input) {
+        if (!this.persons.has(personId))
+            return null;
+        const now = new Date().toISOString();
+        const memory = {
+            id: this.newMemoryId(),
+            person_id: personId,
+            content: input.content,
+            source: input.source ?? "agent",
+            source_session_id: input.source_session_id ?? null,
+            created_at: now,
+            updated_at: now,
+        };
+        this.memories.set(memory.id, memory);
+        return memory;
+    }
+    async listPersonMemories(personId, opts) {
+        const matches = [...this.memories.values()].filter((m) => m.person_id === personId);
+        matches.sort((a, b) => b.created_at.localeCompare(a.created_at));
+        return matches.slice(0, opts.limit);
+    }
+    async deletePersonMemory(memoryId) {
+        return this.memories.delete(memoryId);
+    }
 }
 function aliasKey(personId, name) {
     return `${personId}${name.toLowerCase()}`;

package/dist/adapters/postgres.d.ts

@@ -1,5 +1,5 @@
 import type { Session } from "@hexis-ai/engram-core";
-import type { AliasInfo, AliasUpsert, IdentityInfo, IdentityUpsert, PersonCreate, PersonInfo, PersonUpdate, SessionEvent, SessionInit, SessionUpdate } from "@hexis-ai/engram-sdk";
+import type { AliasInfo, AliasUpsert, IdentityInfo, IdentityUpsert, PersonCreate, PersonInfo, PersonMemory, PersonMemoryCreate, PersonUpdate, SessionEvent, SessionInit, SessionUpdate } from "@hexis-ai/engram-sdk";
 import { type StorageAdapter } from "../storage";
 /**
  * Minimal subset of `postgres` driver's tagged-template surface that this
@@ -26,11 +26,17 @@ export interface PostgresAdapterOptions {
      * Override in tests for determinism.
      */
     newPersonId?: () => string;
+    /**
+     * Generates ids for newly created person-memories. Default:
+     * `mem_${randomShort()}`. Override in tests for determinism.
+     */
+    newMemoryId?: () => string;
 }
 export declare class PostgresAdapter implements StorageAdapter {
     private readonly workspaceId;
     private readonly sql;
     private readonly newPersonId;
+    private readonly newMemoryId;
     constructor(opts: PostgresAdapterOptions);
     /**
      * Apply all pending schema migrations. Safe to call repeatedly and
@@ -62,6 +68,7 @@ export declare class PostgresAdapter implements StorageAdapter {
     createPerson(input: PersonCreate): Promise<PersonInfo>;
     upsertPerson(id: string, input: PersonCreate): Promise<PersonInfo>;
     updatePerson(id: string, patch: PersonUpdate): Promise<PersonInfo | null>;
+    deletePerson(id: string): Promise<boolean>;
     getPerson(id: string): Promise<PersonInfo | null>;
     getPersons(ids: string[]): Promise<PersonInfo[]>;
     listPersons(opts: {
@@ -72,8 +79,14 @@ export declare class PostgresAdapter implements StorageAdapter {
         name: string;
     } & AliasUpsert): Promise<AliasInfo | null>;
     listAliases(personId: string): Promise<AliasInfo[]>;
+    deleteAlias(personId: string, name: string): Promise<boolean>;
     findAliasesByName(name: string): Promise<AliasInfo[]>;
     upsertIdentity(ref: string, input: IdentityUpsert): Promise<IdentityInfo | null>;
     getIdentityByRef(ref: string): Promise<IdentityInfo | null>;
     listIdentitiesByPerson(personId: string): Promise<IdentityInfo[]>;
+    addPersonMemory(personId: string, input: PersonMemoryCreate): Promise<PersonMemory | null>;
+    listPersonMemories(personId: string, opts: {
+        limit: number;
+    }): Promise<PersonMemory[]>;
+    deletePersonMemory(memoryId: string): Promise<boolean>;
 }

package/dist/adapters/postgres.js

@@ -1,14 +1,16 @@
 import { runMigrations } from "../migrator";
-import { foldEvents, newPersonId } from "../storage";
+import { foldEvents, newPersonId, newPersonMemoryId, } from "../storage";
 import { isoString, pickPatch } from "./util";
 export class PostgresAdapter {
     workspaceId;
     sql;
     newPersonId;
+    newMemoryId;
     constructor(opts) {
         this.workspaceId = opts.workspaceId;
         this.sql = opts.sql;
         this.newPersonId = opts.newPersonId ?? newPersonId;
+        this.newMemoryId = opts.newMemoryId ?? newPersonMemoryId;
     }
     /**
      * Apply all pending schema migrations. Safe to call repeatedly and
@@ -304,6 +306,17 @@ export class PostgresAdapter {
             return null;
         return toPersonInfo(rows[0]);
     }
+    async deletePerson(id) {
+        // Aliases / identities / memories vanish via FK ON DELETE CASCADE.
+        // Sessions are not FK'd to engram_persons (participant ids are
+        // opaque text) and are intentionally left alone.
+        const rows = await this.sql `
+      DELETE FROM engram_persons
+      WHERE workspace_id = ${this.workspaceId} AND id = ${id}
+      RETURNING id
+    `;
+        return rows.length > 0;
+    }
     async getPerson(id) {
         const rows = await this.sql `
       SELECT id, display_name, role, team, source, created_at, updated_at
@@ -412,6 +425,18 @@ export class PostgresAdapter {
     `;
         return rows.map(toAliasInfo);
     }
+    async deleteAlias(personId, name) {
+        // name_lower (generated stored) keeps this index-only regardless
+        // of the input casing.
+        const rows = await this.sql `
+      DELETE FROM engram_aliases
+      WHERE workspace_id = ${this.workspaceId}
+        AND person_id    = ${personId}
+        AND name_lower   = ${name.toLowerCase()}
+      RETURNING name
+    `;
+        return rows.length > 0;
+    }
     async findAliasesByName(name) {
         // The `name_lower` column is a STORED generated lower(name) backed
         // by `idx_engram_aliases_name_lower (workspace_id, name_lower)`, so
@@ -495,6 +520,51 @@ export class PostgresAdapter {
     `;
         return rows.map(toIdentityInfo);
     }
+    // --- Person memories ----------------------------------------------
+    async addPersonMemory(personId, input) {
+        // Existence-check + insert in one round-trip via INSERT…SELECT.
+        // Unlike aliases/identities the adapter does NOT auto-create a
+        // stub person — memories are first-class facts about a known
+        // person; writing one for an unknown id is almost always a bug.
+        const id = this.newMemoryId();
+        const rows = await this.sql `
+      INSERT INTO engram_person_memories (
+        workspace_id, id, person_id, content, source, source_session_id
+      )
+      SELECT
+        ${this.workspaceId}, ${id}, ${personId},
+        ${input.content}, ${input.source ?? "agent"},
+        ${input.source_session_id ?? null}
+      WHERE EXISTS (
+        SELECT 1 FROM engram_persons
+        WHERE workspace_id = ${this.workspaceId} AND id = ${personId}
+      )
+      RETURNING id, person_id, content, source, source_session_id,
+                created_at, updated_at
+    `;
+        if (rows.length === 0)
+            return null;
+        return toPersonMemory(rows[0]);
+    }
+    async listPersonMemories(personId, opts) {
+        const rows = await this.sql `
+      SELECT id, person_id, content, source, source_session_id,
+             created_at, updated_at
+      FROM engram_person_memories
+      WHERE workspace_id = ${this.workspaceId} AND person_id = ${personId}
+      ORDER BY created_at DESC
+      LIMIT ${opts.limit}
+    `;
+        return rows.map(toPersonMemory);
+    }
+    async deletePersonMemory(memoryId) {
+        const rows = await this.sql `
+      DELETE FROM engram_person_memories
+      WHERE workspace_id = ${this.workspaceId} AND id = ${memoryId}
+      RETURNING id
+    `;
+        return rows.length > 0;
+    }
 }
 function toPersonInfo(r) {
     return {
@@ -570,3 +640,14 @@ function toIdentityInfo(r) {
         updated_at: isoString(r.updated_at),
     };
 }
+function toPersonMemory(r) {
+    return {
+        id: r.id,
+        person_id: r.person_id,
+        content: r.content,
+        source: r.source,
+        source_session_id: r.source_session_id,
+        created_at: isoString(r.created_at),
+        updated_at: isoString(r.updated_at),
+    };
+}

package/dist/migrations/0010-person-memories.d.ts

@@ -0,0 +1,2 @@
+export declare const name = "0010-person-memories";
+export declare const sql = "\n-- Per-person free-form memory store. ChatGPT/Claude-style \"facts about\n-- this person\" that the host agent reads on each turn and writes via a\n-- save_person_memory tool. Workspace-scoped, soft-FK to engram_persons\n-- so a memory row cannot outlive its person.\nCREATE TABLE IF NOT EXISTS engram_person_memories (\n  workspace_id      TEXT        NOT NULL,\n  id                TEXT        NOT NULL,\n  person_id         TEXT        NOT NULL,\n  content           TEXT        NOT NULL,\n  -- Where the memory came from. 'agent' = saved by the LLM via tool,\n  -- 'manual' = entered by a human (engram-web UI), 'auto' = derived by\n  -- a pipeline (future). Mirrors engram_persons.source so callers can\n  -- filter/render provenance consistently.\n  source            TEXT        NOT NULL DEFAULT 'agent',\n  -- Session that produced this memory. Nullable because UI-entered\n  -- memories have no originating session. No FK \u2014 sessions can be\n  -- purged independently and we don't want a CASCADE to vaporise the\n  -- memory.\n  source_session_id TEXT,\n  created_at        TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  updated_at        TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  PRIMARY KEY (workspace_id, id),\n  FOREIGN KEY (workspace_id, person_id)\n    REFERENCES engram_persons (workspace_id, id) ON DELETE CASCADE\n);\n\n-- Hot path: \"give me this person's N most recent memories\" \u2014 fired\n-- on every agent turn for every participant. Index covers the\n-- (workspace, person) filter and the created_at desc sort.\nCREATE INDEX IF NOT EXISTS idx_engram_person_memories_person_created\n  ON engram_person_memories (workspace_id, person_id, created_at DESC);\n";

package/dist/migrations/0010-person-memories.js

@@ -0,0 +1,34 @@
+export const name = "0010-person-memories";
+export const sql = `
+-- Per-person free-form memory store. ChatGPT/Claude-style "facts about
+-- this person" that the host agent reads on each turn and writes via a
+-- save_person_memory tool. Workspace-scoped, soft-FK to engram_persons
+-- so a memory row cannot outlive its person.
+CREATE TABLE IF NOT EXISTS engram_person_memories (
+  workspace_id      TEXT        NOT NULL,
+  id                TEXT        NOT NULL,
+  person_id         TEXT        NOT NULL,
+  content           TEXT        NOT NULL,
+  -- Where the memory came from. 'agent' = saved by the LLM via tool,
+  -- 'manual' = entered by a human (engram-web UI), 'auto' = derived by
+  -- a pipeline (future). Mirrors engram_persons.source so callers can
+  -- filter/render provenance consistently.
+  source            TEXT        NOT NULL DEFAULT 'agent',
+  -- Session that produced this memory. Nullable because UI-entered
+  -- memories have no originating session. No FK — sessions can be
+  -- purged independently and we don't want a CASCADE to vaporise the
+  -- memory.
+  source_session_id TEXT,
+  created_at        TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at        TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (workspace_id, id),
+  FOREIGN KEY (workspace_id, person_id)
+    REFERENCES engram_persons (workspace_id, id) ON DELETE CASCADE
+);
+
+-- Hot path: "give me this person's N most recent memories" — fired
+-- on every agent turn for every participant. Index covers the
+-- (workspace, person) filter and the created_at desc sort.
+CREATE INDEX IF NOT EXISTS idx_engram_person_memories_person_created
+  ON engram_person_memories (workspace_id, person_id, created_at DESC);
+`;

package/dist/migrations/index.js

@@ -7,6 +7,7 @@ import * as m0006 from "./0006-auth";
 import * as m0007 from "./0007-orgs";
 import * as m0008 from "./0008-trigger-metadata";
 import * as m0009 from "./0009-events-type-index";
+import * as m0010 from "./0010-person-memories";
 /**
  * Schema migrations, applied in array order. Add a new file under
  * `migrations/NNNN-<slug>.ts` exporting `name` and `sql`, then append it
@@ -24,4 +25,5 @@ export const MIGRATIONS = [
     { name: m0007.name, sql: m0007.sql },
     { name: m0008.name, sql: m0008.sql },
     { name: m0009.name, sql: m0009.sql },
+    { name: m0010.name, sql: m0010.sql },
 ];

package/dist/openapi.js

@@ -18,7 +18,7 @@
  * codes stay as-is.
  */
 import { z } from "zod";
-import { addMemberSchema, createOrgSchema, createWorkspaceSchema, eventBatchSchema, issueKeySchema, orgPatchSchema, personCreateSchema, personUpdateSchema, searchRequestSchema, sessionInitSchema, sessionUpdateSchema, aliasUpsertSchema, identityUpsertSchema, workspacePatchSchema, } from "./schemas";
+import { addMemberSchema, createOrgSchema, createWorkspaceSchema, eventBatchSchema, issueKeySchema, orgPatchSchema, personCreateSchema, personMemoryCreateSchema, personUpdateSchema, searchRequestSchema, sessionInitSchema, sessionUpdateSchema, aliasUpsertSchema, identityUpsertSchema, workspacePatchSchema, } from "./schemas";
 /** Convert a Zod schema to a JSON Schema object for an OpenAPI component. */
 function toComponent(schema) {
     const js = z.toJSONSchema(schema);
@@ -237,6 +237,15 @@ function buildPaths() {
                     "401": res("認証エラー"),
                 },
             },
+            delete: {
+                summary: "person を hard-delete する。aliases / identities / memories は FK CASCADE で消える。session の participants 配列に残った id はそのまま（engram は participant id を opaque 文字列として扱う）。",
+                parameters: [pathParam("id", "person id。")],
+                responses: {
+                    "204": res("削除完了"),
+                    "404": res("person が見つからない"),
+                    "401": res("認証エラー"),
+                },
+            },
             get: {
                 summary: "単一の person を取得する。",
                 parameters: [pathParam("id", "person id。")],
@@ -290,6 +299,18 @@ function buildPaths() {
                     "401": res("認証エラー"),
                 },
             },
+            delete: {
+                summary: "person の alias を削除する。name は case-insensitive。",
+                parameters: [
+                    pathParam("id", "person id。"),
+                    pathParam("name", "alias の名前（URL-encoded）。"),
+                ],
+                responses: {
+                    "204": res("削除完了"),
+                    "404": res("alias が見つからない"),
+                    "401": res("認証エラー"),
+                },
+            },
         }),
         "/v1/persons/{id}/identities": tagged("Persons", {
             get: {
@@ -301,6 +322,41 @@ function buildPaths() {
                 },
             },
         }),
+        "/v1/persons/{id}/memories": tagged("Persons", {
+            get: {
+                summary: "この person の memory（ChatGPT/Claude 風の自由文 fact）を新しい順に取得する。harness は会話開始時に participants 全員分をここから prefetch する。",
+                parameters: [pathParam("id", "person id。"), limitParam],
+                responses: {
+                    "200": res("memory 一覧"),
+                    "401": res("認証エラー"),
+                },
+            },
+            post: {
+                summary: "person に memory を追記する。agent からは save_person_memory ツール経由で呼ばれる。",
+                parameters: [pathParam("id", "person id。")],
+                requestBody: jsonBody("PersonMemoryCreate"),
+                responses: {
+                    "201": res("追加された memory"),
+                    "400": res("リクエストボディが不正"),
+                    "404": res("person が見つからない"),
+                    "401": res("認証エラー"),
+                },
+            },
+        }),
+        "/v1/persons/{id}/memories/{memoryId}": tagged("Persons", {
+            delete: {
+                summary: "memory を削除する。person 削除に伴う CASCADE で消えるので、手動削除はキュレーション用途。",
+                parameters: [
+                    pathParam("id", "person id。"),
+                    pathParam("memoryId", "memory id。"),
+                ],
+                responses: {
+                    "204": res("削除完了"),
+                    "404": res("memory が見つからない"),
+                    "401": res("認証エラー"),
+                },
+            },
+        }),
         "/v1/aliases": tagged("Aliases", {
             get: {
                 summary: "ワークスペース全体で alias 名を case-insensitive に逆引き。同名の alias を持つ複数の person を `last_used` desc で返す。`persons` map も同梱。",
@@ -673,6 +729,7 @@ export function buildOpenApiDocument() {
                 EventBatch: toComponent(eventBatchSchema),
                 PersonCreate: toComponent(personCreateSchema),
                 PersonUpdate: toComponent(personUpdateSchema),
+                PersonMemoryCreate: toComponent(personMemoryCreateSchema),
                 AliasUpsert: toComponent(aliasUpsertSchema),
                 IdentityUpsert: toComponent(identityUpsertSchema),
                 SearchRequest: toComponent(searchRequestSchema),

package/dist/routes/persons.d.ts

@@ -3,13 +3,18 @@ import type { Env } from "../context";
 import { type RouteConfig } from "./helpers";
 /**
  * Person routes. Mount under `/v1`:
- *   POST  /v1/persons                    create a person (server allocates the id)
- *   PUT   /v1/persons/:id                upsert at a host-supplied id
- *   PATCH /v1/persons/:id                patch profile fields
- *   GET   /v1/persons/:id                fetch one person
- *   GET   /v1/persons                    list / free-text search persons
- *   GET   /v1/persons/:id/sessions       sessions this person participates in / can view
- *   PUT   /v1/persons/:id/aliases/:name  upsert an alias for this person
- *   GET   /v1/persons/:id/aliases        list aliases for this person (newest-used-first)
+ *   POST   /v1/persons                       create a person (server allocates the id)
+ *   PUT    /v1/persons/:id                   upsert at a host-supplied id
+ *   PATCH  /v1/persons/:id                   patch profile fields
+ *   DELETE /v1/persons/:id                   hard-delete (cascades to aliases / identities / memories)
+ *   GET    /v1/persons/:id                   fetch one person
+ *   GET    /v1/persons                       list / free-text search persons
+ *   GET    /v1/persons/:id/sessions          sessions this person participates in / can view
+ *   PUT    /v1/persons/:id/aliases/:name     upsert an alias for this person
+ *   DELETE /v1/persons/:id/aliases/:name     remove an alias (case-insensitive)
+ *   GET    /v1/persons/:id/aliases           list aliases for this person (newest-used-first)
+ *   GET    /v1/persons/:id/memories          list this person's memories (newest-first)
+ *   POST   /v1/persons/:id/memories          append a memory
+ *   DELETE /v1/persons/:id/memories/:mid     remove a memory
  */
 export declare function personsRoutes(cfg: RouteConfig): Hono<Env>;

package/dist/routes/persons.js

@@ -1,16 +1,21 @@
 import { Hono } from "hono";
-import { aliasUpsertSchema, parseJsonBody, personCreateSchema, personUpdateSchema, } from "../schemas";
+import { aliasUpsertSchema, parseJsonBody, personCreateSchema, personMemoryCreateSchema, personUpdateSchema, } from "../schemas";
 import { clampLimit, resolvePersonMap } from "./helpers";
 /**
  * Person routes. Mount under `/v1`:
- *   POST  /v1/persons                    create a person (server allocates the id)
- *   PUT   /v1/persons/:id                upsert at a host-supplied id
- *   PATCH /v1/persons/:id                patch profile fields
- *   GET   /v1/persons/:id                fetch one person
- *   GET   /v1/persons                    list / free-text search persons
- *   GET   /v1/persons/:id/sessions       sessions this person participates in / can view
- *   PUT   /v1/persons/:id/aliases/:name  upsert an alias for this person
- *   GET   /v1/persons/:id/aliases        list aliases for this person (newest-used-first)
+ *   POST   /v1/persons                       create a person (server allocates the id)
+ *   PUT    /v1/persons/:id                   upsert at a host-supplied id
+ *   PATCH  /v1/persons/:id                   patch profile fields
+ *   DELETE /v1/persons/:id                   hard-delete (cascades to aliases / identities / memories)
+ *   GET    /v1/persons/:id                   fetch one person
+ *   GET    /v1/persons                       list / free-text search persons
+ *   GET    /v1/persons/:id/sessions          sessions this person participates in / can view
+ *   PUT    /v1/persons/:id/aliases/:name     upsert an alias for this person
+ *   DELETE /v1/persons/:id/aliases/:name     remove an alias (case-insensitive)
+ *   GET    /v1/persons/:id/aliases           list aliases for this person (newest-used-first)
+ *   GET    /v1/persons/:id/memories          list this person's memories (newest-first)
+ *   POST   /v1/persons/:id/memories          append a memory
+ *   DELETE /v1/persons/:id/memories/:mid     remove a memory
  */
 export function personsRoutes(cfg) {
     const app = new Hono();
@@ -39,6 +44,13 @@ export function personsRoutes(cfg) {
             return c.json({ error: "person_not_found" }, 404);
         return c.json(p);
     });
+    app.delete("/persons/:id", async (c) => {
+        const id = c.req.param("id");
+        const removed = await c.var.ctx.storage.deletePerson(id);
+        if (!removed)
+            return c.json({ error: "person_not_found" }, 404);
+        return c.body(null, 204);
+    });
     app.get("/persons/:id", async (c) => {
         const id = c.req.param("id");
         const p = await c.var.ctx.storage.getPerson(id);
@@ -68,6 +80,14 @@ export function personsRoutes(cfg) {
         const aliases = await c.var.ctx.storage.listAliases(id);
         return c.json({ aliases });
     });
+    app.delete("/persons/:id/aliases/:name", async (c) => {
+        const id = c.req.param("id");
+        const name = c.req.param("name");
+        const removed = await c.var.ctx.storage.deleteAlias(id, name);
+        if (!removed)
+            return c.json({ error: "alias_not_found" }, 404);
+        return c.body(null, 204);
+    });
     app.get("/persons/:id/identities", async (c) => {
         const id = c.req.param("id");
         const identities = await c.var.ctx.storage.listIdentitiesByPerson(id);
@@ -86,5 +106,29 @@ export function personsRoutes(cfg) {
         const persons = await resolvePersonMap(c.var.ctx.storage, sessions);
         return c.json({ sessions, persons });
     });
+    // --- Person memories -------------------------------------------------
+    app.get("/persons/:id/memories", async (c) => {
+        const id = c.req.param("id");
+        const limit = clampLimit(c, cfg.defaultListLimit, cfg.maxListLimit);
+        const memories = await c.var.ctx.storage.listPersonMemories(id, { limit });
+        return c.json({ memories });
+    });
+    app.post("/persons/:id/memories", async (c) => {
+        const id = c.req.param("id");
+        const body = await parseJsonBody(c, personMemoryCreateSchema);
+        if (body instanceof Response)
+            return body;
+        const memory = await c.var.ctx.storage.addPersonMemory(id, body);
+        if (!memory)
+            return c.json({ error: "person_not_found" }, 404);
+        return c.json(memory, 201);
+    });
+    app.delete("/persons/:id/memories/:memoryId", async (c) => {
+        const memoryId = c.req.param("memoryId");
+        const removed = await c.var.ctx.storage.deletePersonMemory(memoryId);
+        if (!removed)
+            return c.json({ error: "memory_not_found" }, 404);
+        return c.body(null, 204);
+    });
     return app;
 }

package/dist/schemas.d.ts

@@ -131,6 +131,11 @@ export declare const aliasUpsertSchema: z.ZodObject<{
     last_used: z.ZodString;
     increment: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
+export declare const personMemoryCreateSchema: z.ZodObject<{
+    content: z.ZodString;
+    source: z.ZodOptional<z.ZodString>;
+    source_session_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
 export declare const identityUpsertSchema: z.ZodObject<{
     person_id: z.ZodString;
     service: z.ZodString;

package/dist/schemas.js

@@ -114,6 +114,15 @@ export const aliasUpsertSchema = z.object({
         .regex(/^\d{4}-\d{2}-\d{2}/, "expected YYYY-MM-DD"),
     increment: z.boolean().optional(),
 });
+// --- Person memories --------------------------------------------------
+export const personMemoryCreateSchema = z.object({
+    // Free-form fact about the person. Min(1) rejects empty strings —
+    // memories that say nothing are spam noise the engram-web UI would
+    // have to filter anyway.
+    content: z.string().min(1),
+    source: z.string().optional(),
+    source_session_id: z.string().nullable().optional(),
+});
 // --- Identities -------------------------------------------------------
 export const identityUpsertSchema = z.object({
     person_id: z.string().min(1),

package/dist/server.js

@@ -83,13 +83,15 @@ export function createServer(opts) {
             sessionEvents: "GET /v1/sessions/:id/events",
             search: "POST /v1/search",
             persons: "POST/GET /v1/persons",
-            personById: "GET/PUT/PATCH /v1/persons/:id",
+            personById: "GET/PUT/PATCH/DELETE /v1/persons/:id",
             personSessions: "GET /v1/persons/:id/sessions",
             personAliases: "GET /v1/persons/:id/aliases",
-            upsertAlias: "PUT /v1/persons/:id/aliases/:name",
+            upsertAlias: "PUT/DELETE /v1/persons/:id/aliases/:name",
             findAliasesByName: "GET /v1/aliases?name=…",
             identityByRef: "GET/PUT /v1/identities/:ref",
             personIdentities: "GET /v1/persons/:id/identities",
+            personMemories: "GET/POST /v1/persons/:id/memories",
+            deletePersonMemory: "DELETE /v1/persons/:id/memories/:mid",
         },
     }));
     app.get("/healthz", (c) => c.json({ ok: true }));

package/dist/storage.d.ts

@@ -1,5 +1,5 @@
 import type { Session } from "@hexis-ai/engram-core";
-import type { AliasInfo, AliasUpsert, IdentityInfo, IdentityUpsert, PersonCreate, PersonInfo, PersonUpdate, SessionEvent, SessionInit, SessionUpdate } from "@hexis-ai/engram-sdk";
+import type { AliasInfo, AliasUpsert, IdentityInfo, IdentityUpsert, PersonCreate, PersonInfo, PersonMemory, PersonMemoryCreate, PersonUpdate, SessionEvent, SessionInit, SessionUpdate } from "@hexis-ai/engram-sdk";
 /**
  * Storage adapter interface. Each implementation owns persistence for
  * a single workspace's sessions and persons. Multi-tenancy is the host's
@@ -67,6 +67,18 @@ export interface StorageAdapter {
     upsertPerson(id: string, input: PersonCreate): Promise<PersonInfo>;
     /** Update profile fields. Returns the updated record. */
     updatePerson(id: string, patch: PersonUpdate): Promise<PersonInfo | null>;
+    /**
+     * Hard-delete a person. Cascades to engram_aliases, engram_identities,
+     * and engram_person_memories via FK ON DELETE CASCADE. Returns `false`
+     * when the id doesn't exist in this workspace (idempotent — second
+     * call returns false but doesn't throw).
+     *
+     * Sessions are left intact: `participants` / `viewable_by` arrays may
+     * still reference the deleted id. Hosts that need to scrub references
+     * can do so via their own batch pass — engram treats a participant id
+     * as opaque text, not an FK.
+     */
+    deletePerson(id: string): Promise<boolean>;
     getPerson(id: string): Promise<PersonInfo | null>;
     /** Batch fetch — used by response envelopes to inline `persons` maps. */
     getPersons(ids: string[]): Promise<PersonInfo[]>;
@@ -106,6 +118,13 @@ export interface StorageAdapter {
     } & AliasUpsert): Promise<AliasInfo | null>;
     /** A person's aliases, ordered newest-used-first. */
     listAliases(personId: string): Promise<AliasInfo[]>;
+    /**
+     * Delete one alias (`person_id`, `name` case-insensitively).
+     * Returns `false` when no row matched — both "person has no such
+     * alias" and "person doesn't exist" collapse into the same boolean
+     * because callers (curation UI, host cleanup) treat both as no-ops.
+     */
+    deleteAlias(personId: string, name: string): Promise<boolean>;
     /**
      * Workspace-wide lookup by alias name (case-insensitive). Returns
      * every row whose `lower(name)` matches `lower(name)` across all
@@ -129,6 +148,28 @@ export interface StorageAdapter {
     getIdentityByRef(ref: string): Promise<IdentityInfo | null>;
     /** All identities for a person, ordered newest-linked-first. */
     listIdentitiesByPerson(personId: string): Promise<IdentityInfo[]>;
+    /**
+     * Append a free-form memory to a person. Returns `null` when the
+     * person doesn't exist — unlike aliases/identities, memories do not
+     * auto-create a stub person, because writing a memory for a
+     * non-existent id is almost always a programming mistake, not a
+     * race.
+     */
+    addPersonMemory(personId: string, input: PersonMemoryCreate): Promise<PersonMemory | null>;
+    /**
+     * A person's recent memories, ordered newest-first. `limit` caps the
+     * fetched window — the agent harness uses this on every turn so the
+     * adapter must keep it cheap.
+     */
+    listPersonMemories(personId: string, opts: {
+        limit: number;
+    }): Promise<PersonMemory[]>;
+    /**
+     * Remove a single memory by id. Returns `false` when the row is not
+     * found in this workspace (idempotent — callers can ignore the
+     * boolean if they don't care whether the row existed).
+     */
+    deletePersonMemory(memoryId: string): Promise<boolean>;
 }
 /**
  * Pure fold of an event log into the parts a Session needs. Used by adapters
@@ -157,3 +198,10 @@ export declare function foldEvents(row: SessionRow, events: SessionEvent[], now:
  * shape and entropy stay aligned.
  */
 export declare function newPersonId(): string;
+/**
+ * Allocate a fresh person-memory id (`mem_` + 12 alphanumeric chars).
+ * Wider than person ids because memories accumulate fast — twelve
+ * chars buys ~62 bits of entropy, plenty for the foreseeable lifetime
+ * of a workspace.
+ */
+export declare function newPersonMemoryId(): string;

package/dist/storage.js

@@ -58,3 +58,17 @@ export function newPersonId() {
         out += PERSON_ID_ALPHA[b % PERSON_ID_ALPHA.length];
     return out;
 }
+/**
+ * Allocate a fresh person-memory id (`mem_` + 12 alphanumeric chars).
+ * Wider than person ids because memories accumulate fast — twelve
+ * chars buys ~62 bits of entropy, plenty for the foreseeable lifetime
+ * of a workspace.
+ */
+export function newPersonMemoryId() {
+    const buf = new Uint8Array(12);
+    crypto.getRandomValues(buf);
+    let out = "mem_";
+    for (const b of buf)
+        out += PERSON_ID_ALPHA[b % PERSON_ID_ALPHA.length];
+    return out;
+}

package/openapi.json

@@ -524,6 +524,32 @@
         },
         "additionalProperties": false
       },
+      "PersonMemoryCreate": {
+        "type": "object",
+        "properties": {
+          "content": {
+            "type": "string",
+            "minLength": 1
+          },
+          "source": {
+            "type": "string"
+          },
+          "source_session_id": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          }
+        },
+        "required": [
+          "content"
+        ],
+        "additionalProperties": false
+      },
       "AliasUpsert": {
         "type": "object",
         "properties": {
@@ -1225,6 +1251,34 @@
           "Persons"
         ]
       },
+      "delete": {
+        "summary": "person を hard-delete する。aliases / identities / memories は FK CASCADE で消える。session の participants 配列に残った id はそのまま（engram は participant id を opaque 文字列として扱う）。",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "person id。"
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "削除完了"
+          },
+          "401": {
+            "description": "認証エラー"
+          },
+          "404": {
+            "description": "person が見つからない"
+          }
+        },
+        "tags": [
+          "Persons"
+        ]
+      },
       "get": {
         "summary": "単一の person を取得する。",
         "parameters": [
@@ -1390,6 +1444,43 @@
         "tags": [
           "Persons"
         ]
+      },
+      "delete": {
+        "summary": "person の alias を削除する。name は case-insensitive。",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "person id。"
+          },
+          {
+            "name": "name",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "alias の名前（URL-encoded）。"
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "削除完了"
+          },
+          "401": {
+            "description": "認証エラー"
+          },
+          "404": {
+            "description": "alias が見つからない"
+          }
+        },
+        "tags": [
+          "Persons"
+        ]
       }
     },
     "/v1/persons/{id}/identities": {
@@ -1419,6 +1510,123 @@
         ]
       }
     },
+    "/v1/persons/{id}/memories": {
+      "get": {
+        "summary": "この person の memory（ChatGPT/Claude 風の自由文 fact）を新しい順に取得する。harness は会話開始時に participants 全員分をここから prefetch する。",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "person id。"
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "description": "ページサイズ。サーバー側で上限が適用される。"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "memory 一覧"
+          },
+          "401": {
+            "description": "認証エラー"
+          }
+        },
+        "tags": [
+          "Persons"
+        ]
+      },
+      "post": {
+        "summary": "person に memory を追記する。agent からは save_person_memory ツール経由で呼ばれる。",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "person id。"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PersonMemoryCreate"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "追加された memory"
+          },
+          "400": {
+            "description": "リクエストボディが不正"
+          },
+          "401": {
+            "description": "認証エラー"
+          },
+          "404": {
+            "description": "person が見つからない"
+          }
+        },
+        "tags": [
+          "Persons"
+        ]
+      }
+    },
+    "/v1/persons/{id}/memories/{memoryId}": {
+      "delete": {
+        "summary": "memory を削除する。person 削除に伴う CASCADE で消えるので、手動削除はキュレーション用途。",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "person id。"
+          },
+          {
+            "name": "memoryId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "memory id。"
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "削除完了"
+          },
+          "401": {
+            "description": "認証エラー"
+          },
+          "404": {
+            "description": "memory が見つからない"
+          }
+        },
+        "tags": [
+          "Persons"
+        ]
+      }
+    },
     "/v1/aliases": {
       "get": {
         "summary": "ワークスペース全体で alias 名を case-insensitive に逆引き。同名の alias を持つ複数の person を `last_used` desc で返す。`persons` map も同梱。",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hexis-ai/engram-server",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Engram server: ingest agent session events, persist via a pluggable adapter, expose search.",
   "keywords": [
     "engram",
@@ -50,7 +50,7 @@
   },
   "dependencies": {
     "@hexis-ai/engram-core": "^0.3.0",
-    "@hexis-ai/engram-sdk": "^0.16.0",
+    "@hexis-ai/engram-sdk": "^0.17.0",
     "better-auth": "^1.6.11",
     "hono": "^4.6.0",
     "pg": "^8.13.0",