@hexis-ai/engram-server 0.4.0 → 0.6.0

package/dist/adapters/memory.d.ts

@@ -1,5 +1,5 @@
 import type { Session } from "@hexis-ai/engram-core";
-import type { PersonCreate, PersonInfo, PersonUpdate, SessionEvent, SessionInit } from "@hexis-ai/engram-sdk";
+import type { AliasInfo, AliasUpsert, IdentityInfo, IdentityUpsert, PersonCreate, PersonInfo, PersonUpdate, SessionEvent, SessionInit } from "@hexis-ai/engram-sdk";
 import { type StorageAdapter } from "../storage";
 export interface InMemoryAdapterOptions {
     /** Override for tests. Default: `p_${random}` with 8 chars. */
@@ -12,6 +12,10 @@ export interface InMemoryAdapterOptions {
 export declare class InMemoryAdapter implements StorageAdapter {
     private readonly sessions;
     private readonly persons;
+    /** Keyed by `${personId} ${name.toLowerCase()}` — see `aliasKey` below. */
+    private readonly aliases;
+    /** Keyed by ref (e.g. `slack:U12345`). */
+    private readonly identities;
     private readonly newPersonId;
     constructor(opts?: InMemoryAdapterOptions);
     createSession(init: SessionInit & {
@@ -39,4 +43,11 @@ export declare class InMemoryAdapter implements StorageAdapter {
         limit: number;
         q?: string;
     }): Promise<PersonInfo[]>;
+    upsertAlias(personId: string, input: {
+        name: string;
+    } & AliasUpsert): Promise<AliasInfo | null>;
+    listAliases(personId: string): Promise<AliasInfo[]>;
+    upsertIdentity(ref: string, input: IdentityUpsert): Promise<IdentityInfo | null>;
+    getIdentityByRef(ref: string): Promise<IdentityInfo | null>;
+    listIdentitiesByPerson(personId: string): Promise<IdentityInfo[]>;
 }

package/dist/adapters/memory.js

@@ -13,6 +13,10 @@ function defaultPersonId() {
 export class InMemoryAdapter {
     sessions = new Map();
     persons = new Map();
+    /** Keyed by `${personId} ${name.toLowerCase()}` — see `aliasKey` below. */
+    aliases = new Map();
+    /** Keyed by ref (e.g. `slack:U12345`). */
+    identities = new Map();
     newPersonId;
     constructor(opts = {}) {
         this.newPersonId = opts.newPersonId ?? defaultPersonId;
@@ -158,4 +162,70 @@ export class InMemoryAdapter {
         matched.sort((a, b) => b.updated_at.localeCompare(a.updated_at));
         return matched.slice(0, opts.limit);
     }
+    // --- Aliases ------------------------------------------------------
+    async upsertAlias(personId, input) {
+        if (!this.persons.has(personId))
+            return null;
+        const key = aliasKey(personId, input.name);
+        const now = new Date().toISOString();
+        const existing = this.aliases.get(key);
+        const increment = input.increment ?? true;
+        if (existing && !increment) {
+            // Idempotent backfill: keep the existing row as-is.
+            return existing;
+        }
+        const next = {
+            person_id: personId,
+            name: existing?.name ?? input.name,
+            caller: input.caller,
+            usage_count: existing ? existing.usage_count + 1 : 1,
+            last_used: input.last_used,
+            created_at: existing?.created_at ?? now,
+            updated_at: now,
+        };
+        this.aliases.set(key, next);
+        return next;
+    }
+    async listAliases(personId) {
+        const matches = [...this.aliases.values()].filter((a) => a.person_id === personId);
+        matches.sort((a, b) => b.last_used.localeCompare(a.last_used));
+        return matches;
+    }
+    // --- Identities ---------------------------------------------------
+    async upsertIdentity(ref, input) {
+        if (!this.persons.has(input.person_id))
+            return null;
+        const now = new Date().toISOString();
+        const existing = this.identities.get(ref);
+        const next = {
+            ref,
+            person_id: input.person_id,
+            service: input.service,
+            external_id: input.external_id,
+            display_name: input.display_name !== undefined
+                ? input.display_name
+                : existing?.display_name ?? null,
+            source: input.source !== undefined ? input.source : existing?.source ?? null,
+            is_primary: input.is_primary !== undefined
+                ? input.is_primary
+                : existing?.is_primary ?? null,
+            picture: input.picture !== undefined ? input.picture : existing?.picture ?? null,
+            linked_at: input.linked_at,
+            created_at: existing?.created_at ?? now,
+            updated_at: now,
+        };
+        this.identities.set(ref, next);
+        return next;
+    }
+    async getIdentityByRef(ref) {
+        return this.identities.get(ref) ?? null;
+    }
+    async listIdentitiesByPerson(personId) {
+        const matches = [...this.identities.values()].filter((i) => i.person_id === personId);
+        matches.sort((a, b) => b.linked_at.localeCompare(a.linked_at));
+        return matches;
+    }
+}
+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 { PersonCreate, PersonInfo, PersonUpdate, SessionEvent, SessionInit } from "@hexis-ai/engram-sdk";
+import type { AliasInfo, AliasUpsert, IdentityInfo, IdentityUpsert, PersonCreate, PersonInfo, PersonUpdate, SessionEvent, SessionInit } from "@hexis-ai/engram-sdk";
 import { type StorageAdapter } from "../storage";
 /**
  * Minimal subset of `postgres` driver's tagged-template surface that this
@@ -56,4 +56,11 @@ export declare class PostgresAdapter implements StorageAdapter {
         limit: number;
         q?: string;
     }): Promise<PersonInfo[]>;
+    upsertAlias(personId: string, input: {
+        name: string;
+    } & AliasUpsert): Promise<AliasInfo | null>;
+    listAliases(personId: string): Promise<AliasInfo[]>;
+    upsertIdentity(ref: string, input: IdentityUpsert): Promise<IdentityInfo | null>;
+    getIdentityByRef(ref: string): Promise<IdentityInfo | null>;
+    listIdentitiesByPerson(personId: string): Promise<IdentityInfo[]>;
 }

package/dist/adapters/postgres.js

@@ -237,6 +237,117 @@ export class PostgresAdapter {
     `;
         return rows.map(toPersonInfo);
     }
+    // --- Aliases ------------------------------------------------------
+    async upsertAlias(personId, input) {
+        // Pre-check rather than rely on the FK so unknown persons return
+        // `null` instead of throwing a constraint violation.
+        const personExists = await this.sql `
+      SELECT id FROM engram_persons
+      WHERE workspace_id = ${this.workspaceId} AND id = ${personId}
+      LIMIT 1
+    `;
+        if (personExists.length === 0)
+            return null;
+        const increment = input.increment ?? true;
+        // Branch on the upsert behaviour. `increment=true` bumps usage_count
+        // and replaces caller/last_used; `increment=false` is idempotent —
+        // a no-op when the row already exists.
+        const rows = increment
+            ? await this.sql `
+          INSERT INTO engram_aliases (workspace_id, person_id, name, caller, usage_count, last_used)
+          VALUES (
+            ${this.workspaceId}, ${personId}, ${input.name},
+            ${input.caller}, 1, ${input.last_used}
+          )
+          ON CONFLICT (workspace_id, person_id, name_lower) DO UPDATE SET
+            usage_count = engram_aliases.usage_count + 1,
+            caller      = EXCLUDED.caller,
+            last_used   = EXCLUDED.last_used,
+            updated_at  = now()
+          RETURNING person_id, name, caller, usage_count, last_used, created_at, updated_at
+        `
+            : await this.sql `
+          INSERT INTO engram_aliases (workspace_id, person_id, name, caller, usage_count, last_used)
+          VALUES (
+            ${this.workspaceId}, ${personId}, ${input.name},
+            ${input.caller}, 1, ${input.last_used}
+          )
+          ON CONFLICT (workspace_id, person_id, name_lower) DO UPDATE SET
+            -- No-op update so RETURNING still produces a row.
+            updated_at = engram_aliases.updated_at
+          RETURNING person_id, name, caller, usage_count, last_used, created_at, updated_at
+        `;
+        return toAliasInfo(rows[0]);
+    }
+    async listAliases(personId) {
+        const rows = await this.sql `
+      SELECT person_id, name, caller, usage_count, last_used, created_at, updated_at
+      FROM engram_aliases
+      WHERE workspace_id = ${this.workspaceId} AND person_id = ${personId}
+      ORDER BY last_used DESC
+    `;
+        return rows.map(toAliasInfo);
+    }
+    // --- Identities ---------------------------------------------------
+    async upsertIdentity(ref, input) {
+        // Pre-check rather than rely on the FK so unknown persons return
+        // `null` instead of throwing a constraint violation.
+        const personExists = await this.sql `
+      SELECT id FROM engram_persons
+      WHERE workspace_id = ${this.workspaceId} AND id = ${input.person_id}
+      LIMIT 1
+    `;
+        if (personExists.length === 0)
+            return null;
+        const rows = await this.sql `
+      INSERT INTO engram_identities (
+        workspace_id, ref, person_id, service, external_id,
+        display_name, source, is_primary, picture, linked_at
+      )
+      VALUES (
+        ${this.workspaceId}, ${ref}, ${input.person_id},
+        ${input.service}, ${input.external_id},
+        ${input.display_name ?? null}, ${input.source ?? null},
+        ${input.is_primary ?? null}, ${input.picture ?? null},
+        ${input.linked_at}
+      )
+      ON CONFLICT (workspace_id, ref) DO UPDATE SET
+        person_id    = EXCLUDED.person_id,
+        service      = EXCLUDED.service,
+        external_id  = EXCLUDED.external_id,
+        display_name = COALESCE(EXCLUDED.display_name, engram_identities.display_name),
+        source       = COALESCE(EXCLUDED.source,       engram_identities.source),
+        is_primary   = COALESCE(EXCLUDED.is_primary,   engram_identities.is_primary),
+        picture      = COALESCE(EXCLUDED.picture,      engram_identities.picture),
+        linked_at    = EXCLUDED.linked_at,
+        updated_at   = now()
+      RETURNING ref, person_id, service, external_id, display_name, source,
+                is_primary, picture, linked_at, created_at, updated_at
+    `;
+        return toIdentityInfo(rows[0]);
+    }
+    async getIdentityByRef(ref) {
+        const rows = await this.sql `
+      SELECT ref, person_id, service, external_id, display_name, source,
+             is_primary, picture, linked_at, created_at, updated_at
+      FROM engram_identities
+      WHERE workspace_id = ${this.workspaceId} AND ref = ${ref}
+      LIMIT 1
+    `;
+        if (rows.length === 0)
+            return null;
+        return toIdentityInfo(rows[0]);
+    }
+    async listIdentitiesByPerson(personId) {
+        const rows = await this.sql `
+      SELECT ref, person_id, service, external_id, display_name, source,
+             is_primary, picture, linked_at, created_at, updated_at
+      FROM engram_identities
+      WHERE workspace_id = ${this.workspaceId} AND person_id = ${personId}
+      ORDER BY linked_at DESC
+    `;
+        return rows.map(toIdentityInfo);
+    }
 }
 function toPersonInfo(r) {
     const toIso = (v) => (typeof v === "string" ? v : v.toISOString());
@@ -247,3 +358,39 @@ function toPersonInfo(r) {
         updated_at: toIso(r.updated_at),
     };
 }
+function toAliasInfo(r) {
+    const toIso = (v) => (typeof v === "string" ? v : v.toISOString());
+    // last_used is a DATE column; postgres-js returns it as a Date at UTC
+    // midnight. Render as plain YYYY-MM-DD to match the wire type.
+    const lastUsed = typeof r.last_used === "string"
+        ? r.last_used.slice(0, 10)
+        : r.last_used.toISOString().slice(0, 10);
+    return {
+        person_id: r.person_id,
+        name: r.name,
+        caller: r.caller,
+        usage_count: r.usage_count,
+        last_used: lastUsed,
+        created_at: toIso(r.created_at),
+        updated_at: toIso(r.updated_at),
+    };
+}
+function toIdentityInfo(r) {
+    const toIso = (v) => (typeof v === "string" ? v : v.toISOString());
+    const linkedAt = typeof r.linked_at === "string"
+        ? r.linked_at.slice(0, 10)
+        : r.linked_at.toISOString().slice(0, 10);
+    return {
+        ref: r.ref,
+        person_id: r.person_id,
+        service: r.service,
+        external_id: r.external_id,
+        display_name: r.display_name,
+        source: r.source,
+        is_primary: r.is_primary,
+        picture: r.picture,
+        linked_at: linkedAt,
+        created_at: toIso(r.created_at),
+        updated_at: toIso(r.updated_at),
+    };
+}

package/dist/migrations/0002-aliases.d.ts

@@ -0,0 +1,2 @@
+export declare const name = "0002-aliases";
+export declare const sql = "\n-- Per-person alias history. Mirrors monet's `aliases` table at the\n-- canonical-engram level so identity resolution can move out of monet\n-- once consumers catch up. Keyed by name_lower (case-insensitive,\n-- DB-generated) so case variants collapse.\nCREATE TABLE IF NOT EXISTS engram_aliases (\n  workspace_id  TEXT NOT NULL,\n  person_id     TEXT NOT NULL,\n  name          TEXT NOT NULL,\n  name_lower    TEXT GENERATED ALWAYS AS (lower(name)) STORED,\n  caller        TEXT NOT NULL,\n  usage_count   INTEGER NOT NULL DEFAULT 1,\n  last_used     DATE NOT NULL,\n  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  updated_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  PRIMARY KEY (workspace_id, person_id, name_lower),\n  FOREIGN KEY (workspace_id, person_id)\n    REFERENCES engram_persons(workspace_id, id) ON DELETE CASCADE\n);\n\n-- Reverse lookup: \"who answers to this name?\" is the common identity-\n-- resolution query and benefits from an index on the lowercased form.\nCREATE INDEX IF NOT EXISTS idx_engram_aliases_name_lower\n  ON engram_aliases (workspace_id, name_lower);\n\n-- Forward lookup: list all of a person's aliases by recency.\nCREATE INDEX IF NOT EXISTS idx_engram_aliases_person_last_used\n  ON engram_aliases (workspace_id, person_id, last_used DESC);\n";

package/dist/migrations/0002-aliases.js

@@ -0,0 +1,30 @@
+export const name = "0002-aliases";
+export const sql = `
+-- Per-person alias history. Mirrors monet's \`aliases\` table at the
+-- canonical-engram level so identity resolution can move out of monet
+-- once consumers catch up. Keyed by name_lower (case-insensitive,
+-- DB-generated) so case variants collapse.
+CREATE TABLE IF NOT EXISTS engram_aliases (
+  workspace_id  TEXT NOT NULL,
+  person_id     TEXT NOT NULL,
+  name          TEXT NOT NULL,
+  name_lower    TEXT GENERATED ALWAYS AS (lower(name)) STORED,
+  caller        TEXT NOT NULL,
+  usage_count   INTEGER NOT NULL DEFAULT 1,
+  last_used     DATE NOT NULL,
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (workspace_id, person_id, name_lower),
+  FOREIGN KEY (workspace_id, person_id)
+    REFERENCES engram_persons(workspace_id, id) ON DELETE CASCADE
+);
+
+-- Reverse lookup: \"who answers to this name?\" is the common identity-
+-- resolution query and benefits from an index on the lowercased form.
+CREATE INDEX IF NOT EXISTS idx_engram_aliases_name_lower
+  ON engram_aliases (workspace_id, name_lower);
+
+-- Forward lookup: list all of a person's aliases by recency.
+CREATE INDEX IF NOT EXISTS idx_engram_aliases_person_last_used
+  ON engram_aliases (workspace_id, person_id, last_used DESC);
+`;

package/dist/migrations/0003-identities.d.ts

@@ -0,0 +1,2 @@
+export declare const name = "0003-identities";
+export declare const sql = "\n-- External identity \u2192 person mapping. Mirrors monet's `identities`\n-- table at the canonical-engram level so identity resolution\n-- (slack:U12345 \u2192 person id, email:foo@bar \u2192 person id, \u2026) can move\n-- out of monet once consumers catch up.\n--\n-- Ref is workspace-scoped here even though monet's PK is just `ref`;\n-- engram is multi-tenant from the floor up.\nCREATE TABLE IF NOT EXISTS engram_identities (\n  workspace_id  TEXT NOT NULL,\n  ref           TEXT NOT NULL,\n  person_id     TEXT NOT NULL,\n  service       TEXT NOT NULL,\n  external_id   TEXT NOT NULL,\n  display_name  TEXT,\n  source        TEXT,\n  is_primary    BOOLEAN,\n  picture       TEXT,\n  linked_at     DATE NOT NULL,\n  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  updated_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  PRIMARY KEY (workspace_id, ref),\n  FOREIGN KEY (workspace_id, person_id)\n    REFERENCES engram_persons(workspace_id, id) ON DELETE CASCADE\n);\n\n-- The two query shapes the resolver needs.\nCREATE INDEX IF NOT EXISTS idx_engram_identities_person\n  ON engram_identities (workspace_id, person_id);\nCREATE INDEX IF NOT EXISTS idx_engram_identities_service_external\n  ON engram_identities (workspace_id, service, external_id);\n";

package/dist/migrations/0003-identities.js

@@ -0,0 +1,33 @@
+export const name = "0003-identities";
+export const sql = `
+-- External identity → person mapping. Mirrors monet's \`identities\`
+-- table at the canonical-engram level so identity resolution
+-- (slack:U12345 → person id, email:foo@bar → person id, …) can move
+-- out of monet once consumers catch up.
+--
+-- Ref is workspace-scoped here even though monet's PK is just \`ref\`;
+-- engram is multi-tenant from the floor up.
+CREATE TABLE IF NOT EXISTS engram_identities (
+  workspace_id  TEXT NOT NULL,
+  ref           TEXT NOT NULL,
+  person_id     TEXT NOT NULL,
+  service       TEXT NOT NULL,
+  external_id   TEXT NOT NULL,
+  display_name  TEXT,
+  source        TEXT,
+  is_primary    BOOLEAN,
+  picture       TEXT,
+  linked_at     DATE NOT NULL,
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (workspace_id, ref),
+  FOREIGN KEY (workspace_id, person_id)
+    REFERENCES engram_persons(workspace_id, id) ON DELETE CASCADE
+);
+
+-- The two query shapes the resolver needs.
+CREATE INDEX IF NOT EXISTS idx_engram_identities_person
+  ON engram_identities (workspace_id, person_id);
+CREATE INDEX IF NOT EXISTS idx_engram_identities_service_external
+  ON engram_identities (workspace_id, service, external_id);
+`;

package/dist/migrations/index.js

@@ -1,4 +1,6 @@
 import * as m0001 from "./0001-baseline";
+import * as m0002 from "./0002-aliases";
+import * as m0003 from "./0003-identities";
 /**
  * Schema migrations, applied in array order. Add a new file under
  * `migrations/NNNN-<slug>.ts` exporting `name` and `sql`, then append it
@@ -6,4 +8,8 @@ import * as m0001 from "./0001-baseline";
  * EXISTS, ADD COLUMN IF NOT EXISTS, etc.) so a first apply on a DB that
  * predates the migrator is a no-op.
  */
-export const MIGRATIONS = [{ name: m0001.name, sql: m0001.sql }];
+export const MIGRATIONS = [
+    { name: m0001.name, sql: m0001.sql },
+    { name: m0002.name, sql: m0002.sql },
+    { name: m0003.name, sql: m0003.sql },
+];

package/dist/openapi.js

@@ -58,6 +58,10 @@ const TAG_DEFS = [
     { name: "Sessions", description: "セッションの作成・取得・イベント追加" },
     { name: "Search", description: "ワークスペースコーパスへのスコアリング検索" },
     { name: "Persons", description: "person の作成・更新・検索" },
+    {
+        name: "Identities",
+        description: "外部 ID（slack: / email: など）の resolve と upsert",
+    },
     {
         name: "Workspaces (admin)",
         description: "ワークスペースの管理（管理者トークン必須）",
@@ -231,6 +235,64 @@ function buildPaths() {
                 },
             },
         }),
+        "/v1/persons/{id}/aliases": tagged("Persons", {
+            get: {
+                summary: "この person の alias 一覧を取得する（直近使用が先頭）。",
+                parameters: [pathParam("id", "person id。")],
+                responses: {
+                    "200": res("alias 一覧"),
+                    "401": res("認証エラー"),
+                },
+            },
+        }),
+        "/v1/persons/{id}/aliases/{name}": tagged("Persons", {
+            put: {
+                summary: "person に alias を upsert する。name は case-insensitive で比較される。",
+                parameters: [
+                    pathParam("id", "person id。"),
+                    pathParam("name", "alias の名前（URL-encoded）。"),
+                ],
+                requestBody: jsonBody("AliasUpsert"),
+                responses: {
+                    "200": res("upsert された alias"),
+                    "400": res("リクエストボディが不正"),
+                    "404": res("person が見つからない"),
+                    "401": res("認証エラー"),
+                },
+            },
+        }),
+        "/v1/persons/{id}/identities": tagged("Persons", {
+            get: {
+                summary: "この person のすべての identity を取得する（直近 link が先頭）。",
+                parameters: [pathParam("id", "person id。")],
+                responses: {
+                    "200": res("identity 一覧"),
+                    "401": res("認証エラー"),
+                },
+            },
+        }),
+        "/v1/identities/{ref}": tagged("Identities", {
+            put: {
+                summary: "ref（例: `slack:U12345`、`email:foo@bar.com`）で identity を upsert する。",
+                parameters: [pathParam("ref", "global identity ref（URL-encoded）。")],
+                requestBody: jsonBody("IdentityUpsert"),
+                responses: {
+                    "200": res("upsert された identity"),
+                    "400": res("リクエストボディが不正"),
+                    "404": res("person_id が見つからない"),
+                    "401": res("認証エラー"),
+                },
+            },
+            get: {
+                summary: "ref から identity を resolve する。",
+                parameters: [pathParam("ref", "global identity ref（URL-encoded）。")],
+                responses: {
+                    "200": res("identity 情報"),
+                    "404": res("ref が見つからない"),
+                    "401": res("認証エラー"),
+                },
+            },
+        }),
         "/admin/v1/workspaces": tagged("Workspaces (admin)", {
             post: {
                 summary: "ワークスペースを作成する（デフォルトで初期キーも発行する）。",

package/dist/routes/identities.d.ts

@@ -0,0 +1,14 @@
+import { Hono } from "hono";
+import type { Env } from "../context";
+import type { RouteConfig } from "./helpers";
+/**
+ * Identity routes. Mount under `/v1`:
+ *   PUT /v1/identities/:ref  upsert by global ref (e.g. `slack:U12345`)
+ *   GET /v1/identities/:ref  resolve a ref to its identity record
+ *
+ * The "list this person's identities" endpoint is exposed by the
+ * persons routes at `/v1/persons/:id/identities` because that's the
+ * natural client mental model — start from a person, fan out — not
+ * start from a ref.
+ */
+export declare function identitiesRoutes(_cfg: RouteConfig): Hono<Env>;

package/dist/routes/identities.js

@@ -0,0 +1,33 @@
+import { Hono } from "hono";
+import { identityUpsertSchema, parseJsonBody } from "../schemas";
+/**
+ * Identity routes. Mount under `/v1`:
+ *   PUT /v1/identities/:ref  upsert by global ref (e.g. `slack:U12345`)
+ *   GET /v1/identities/:ref  resolve a ref to its identity record
+ *
+ * The "list this person's identities" endpoint is exposed by the
+ * persons routes at `/v1/persons/:id/identities` because that's the
+ * natural client mental model — start from a person, fan out — not
+ * start from a ref.
+ */
+export function identitiesRoutes(_cfg) {
+    const app = new Hono();
+    app.put("/identities/:ref", async (c) => {
+        const ref = c.req.param("ref");
+        const body = await parseJsonBody(c, identityUpsertSchema);
+        if (body instanceof Response)
+            return body;
+        const identity = await c.var.ctx.storage.upsertIdentity(ref, body);
+        if (!identity)
+            return c.json({ error: "person_not_found" }, 404);
+        return c.json(identity);
+    });
+    app.get("/identities/:ref", async (c) => {
+        const ref = c.req.param("ref");
+        const identity = await c.var.ctx.storage.getIdentityByRef(ref);
+        if (!identity)
+            return c.json({ error: "identity_not_found" }, 404);
+        return c.json(identity);
+    });
+    return app;
+}

package/dist/routes/persons.d.ts

@@ -3,11 +3,13 @@ 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
+ *   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)
  */
 export declare function personsRoutes(cfg: RouteConfig): Hono<Env>;

package/dist/routes/persons.js

@@ -1,14 +1,16 @@
 import { Hono } from "hono";
-import { parseJsonBody, personCreateSchema, personUpdateSchema } from "../schemas";
+import { aliasUpsertSchema, parseJsonBody, personCreateSchema, 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
+ *   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)
  */
 export function personsRoutes(cfg) {
     const app = new Hono();
@@ -50,6 +52,27 @@ export function personsRoutes(cfg) {
         const persons = await c.var.ctx.storage.listPersons({ limit, q });
         return c.json({ persons });
     });
+    app.put("/persons/:id/aliases/:name", async (c) => {
+        const id = c.req.param("id");
+        const name = c.req.param("name");
+        const body = await parseJsonBody(c, aliasUpsertSchema);
+        if (body instanceof Response)
+            return body;
+        const alias = await c.var.ctx.storage.upsertAlias(id, { name, ...body });
+        if (!alias)
+            return c.json({ error: "person_not_found" }, 404);
+        return c.json(alias);
+    });
+    app.get("/persons/:id/aliases", async (c) => {
+        const id = c.req.param("id");
+        const aliases = await c.var.ctx.storage.listAliases(id);
+        return c.json({ aliases });
+    });
+    app.get("/persons/:id/identities", async (c) => {
+        const id = c.req.param("id");
+        const identities = await c.var.ctx.storage.listIdentitiesByPerson(id);
+        return c.json({ identities });
+    });
     app.get("/persons/:id/sessions", async (c) => {
         const id = c.req.param("id");
         const limit = clampLimit(c, cfg.defaultListLimit, cfg.maxListLimit);

package/dist/schemas.d.ts

@@ -66,6 +66,21 @@ export declare const personCreateSchema: z.ZodObject<{
 export declare const personUpdateSchema: z.ZodObject<{
     display_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
+export declare const aliasUpsertSchema: z.ZodObject<{
+    caller: z.ZodString;
+    last_used: z.ZodString;
+    increment: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const identityUpsertSchema: z.ZodObject<{
+    person_id: z.ZodString;
+    service: z.ZodString;
+    external_id: z.ZodString;
+    display_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    source: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    is_primary: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    picture: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    linked_at: z.ZodString;
+}, z.core.$strip>;
 export declare const searchRequestSchema: z.ZodObject<{
     query: z.ZodUnion<readonly [z.ZodObject<{
         sessionId: z.ZodString;

package/dist/schemas.js

@@ -56,6 +56,29 @@ export const personCreateSchema = z.object({
 export const personUpdateSchema = z.object({
     display_name: z.string().nullable().optional(),
 });
+// --- Aliases ----------------------------------------------------------
+export const aliasUpsertSchema = z.object({
+    caller: z.string().min(1),
+    // YYYY-MM-DD; loose-validate so callers can also pass an ISO timestamp
+    // and the server will accept the date prefix.
+    last_used: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}/, "expected YYYY-MM-DD"),
+    increment: z.boolean().optional(),
+});
+// --- Identities -------------------------------------------------------
+export const identityUpsertSchema = z.object({
+    person_id: z.string().min(1),
+    service: z.string().min(1),
+    external_id: z.string().min(1),
+    display_name: z.string().nullable().optional(),
+    source: z.string().nullable().optional(),
+    is_primary: z.boolean().nullable().optional(),
+    picture: z.string().nullable().optional(),
+    linked_at: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}/, "expected YYYY-MM-DD"),
+});
 // --- Search ----------------------------------------------------------
 const searchQuerySchema = z.union([
     z.object({ sessionId: z.string().min(1) }),

package/dist/server.js

@@ -3,6 +3,7 @@ import { log, newRequestId } from "./logger";
 import { createAdminRouter } from "./admin";
 import { sessionsRoutes } from "./routes/sessions";
 import { personsRoutes } from "./routes/persons";
+import { identitiesRoutes } from "./routes/identities";
 import { searchRoutes } from "./routes/search";
 /**
  * Build the engram HTTP app. Wiring only: this sets up cross-cutting
@@ -58,6 +59,10 @@ export function createServer(opts) {
             persons: "POST/GET /v1/persons",
             personById: "GET/PUT/PATCH /v1/persons/:id",
             personSessions: "GET /v1/persons/:id/sessions",
+            personAliases: "GET /v1/persons/:id/aliases",
+            upsertAlias: "PUT /v1/persons/:id/aliases/:name",
+            identityByRef: "GET/PUT /v1/identities/:ref",
+            personIdentities: "GET /v1/persons/:id/identities",
         },
     }));
     app.get("/healthz", (c) => c.json({ ok: true }));
@@ -77,10 +82,12 @@ export function createServer(opts) {
         await next();
     });
     // Identity probe — echoes the workspace the caller's key resolves to.
-    // Used by clients (e.g. engram-web) to label which tenant they're viewing.
+    // Used by host clients (e.g. monet's `/v1/engram/*` proxy) to label
+    // which tenant they're viewing.
     app.get("/v1/me", (c) => c.json({ workspaceId: c.var.ctx.workspaceId }));
     app.route("/v1", sessionsRoutes(cfg));
     app.route("/v1", personsRoutes(cfg));
+    app.route("/v1", identitiesRoutes(cfg));
     app.route("/v1", searchRoutes(cfg));
     return app;
 }

package/dist/storage.d.ts

@@ -1,5 +1,5 @@
 import type { Session } from "@hexis-ai/engram-core";
-import type { PersonCreate, PersonInfo, PersonUpdate, SessionEvent, SessionInit } from "@hexis-ai/engram-sdk";
+import type { AliasInfo, AliasUpsert, IdentityInfo, IdentityUpsert, PersonCreate, PersonInfo, PersonUpdate, SessionEvent, SessionInit } 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
@@ -60,6 +60,36 @@ export interface StorageAdapter {
         channel?: string;
         scope?: "participant" | "viewable";
     }): Promise<Session[]>;
+    /**
+     * Upsert a name → person mapping. Names collapse case-insensitively
+     * (the row is keyed by `(person_id, lower(name))`).
+     *
+     * - `increment: true` (default): if the alias already exists, bump
+     *   `usage_count` by 1 and replace `caller` / `last_used` with the
+     *   input values.
+     * - `increment: false`: if the row already exists, do not touch it.
+     *
+     * Returns `null` if `personId` does not exist (engram_aliases FKs into
+     * engram_persons).
+     */
+    upsertAlias(personId: string, input: {
+        name: string;
+    } & AliasUpsert): Promise<AliasInfo | null>;
+    /** A person's aliases, ordered newest-used-first. */
+    listAliases(personId: string): Promise<AliasInfo[]>;
+    /**
+     * Upsert by `ref` (e.g. `slack:U12345`). Idempotent: writing the same
+     * ref multiple times converges. If the ref points to a different
+     * person than before, the row's `person_id` is updated — refs are
+     * the global handle, persons are reassignable underneath.
+     *
+     * Returns `null` if `input.person_id` does not exist.
+     */
+    upsertIdentity(ref: string, input: IdentityUpsert): Promise<IdentityInfo | null>;
+    /** Lookup by ref. Returns null if unknown. */
+    getIdentityByRef(ref: string): Promise<IdentityInfo | null>;
+    /** All identities for a person, ordered newest-linked-first. */
+    listIdentitiesByPerson(personId: string): Promise<IdentityInfo[]>;
 }
 /**
  * Pure fold of an event log into the parts a Session needs. Used by adapters

package/openapi.json

@@ -22,6 +22,10 @@
       "name": "Persons",
       "description": "person の作成・更新・検索"
     },
+    {
+      "name": "Identities",
+      "description": "外部 ID（slack: / email: など）の resolve と upsert"
+    },
     {
       "name": "Workspaces (admin)",
       "description": "ワークスペースの管理（管理者トークン必須）"
@@ -798,6 +802,183 @@
         ]
       }
     },
+    "/v1/persons/{id}/aliases": {
+      "get": {
+        "summary": "この person の alias 一覧を取得する（直近使用が先頭）。",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "person id。"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "alias 一覧"
+          },
+          "401": {
+            "description": "認証エラー"
+          }
+        },
+        "tags": [
+          "Persons"
+        ]
+      }
+    },
+    "/v1/persons/{id}/aliases/{name}": {
+      "put": {
+        "summary": "person に alias を upsert する。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）。"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AliasUpsert"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "upsert された alias"
+          },
+          "400": {
+            "description": "リクエストボディが不正"
+          },
+          "401": {
+            "description": "認証エラー"
+          },
+          "404": {
+            "description": "person が見つからない"
+          }
+        },
+        "tags": [
+          "Persons"
+        ]
+      }
+    },
+    "/v1/persons/{id}/identities": {
+      "get": {
+        "summary": "この person のすべての identity を取得する（直近 link が先頭）。",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "person id。"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "identity 一覧"
+          },
+          "401": {
+            "description": "認証エラー"
+          }
+        },
+        "tags": [
+          "Persons"
+        ]
+      }
+    },
+    "/v1/identities/{ref}": {
+      "put": {
+        "summary": "ref（例: `slack:U12345`、`email:foo@bar.com`）で identity を upsert する。",
+        "parameters": [
+          {
+            "name": "ref",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "global identity ref（URL-encoded）。"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/IdentityUpsert"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "upsert された identity"
+          },
+          "400": {
+            "description": "リクエストボディが不正"
+          },
+          "401": {
+            "description": "認証エラー"
+          },
+          "404": {
+            "description": "person_id が見つからない"
+          }
+        },
+        "tags": [
+          "Identities"
+        ]
+      },
+      "get": {
+        "summary": "ref から identity を resolve する。",
+        "parameters": [
+          {
+            "name": "ref",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "global identity ref（URL-encoded）。"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "identity 情報"
+          },
+          "401": {
+            "description": "認証エラー"
+          },
+          "404": {
+            "description": "ref が見つからない"
+          }
+        },
+        "tags": [
+          "Identities"
+        ]
+      }
+    },
     "/admin/v1/workspaces": {
       "post": {
         "summary": "ワークスペースを作成する（デフォルトで初期キーも発行する）。",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hexis-ai/engram-server",
-  "version": "0.4.0",
+  "version": "0.6.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.1.5",
-    "@hexis-ai/engram-sdk": "^0.3.0",
+    "@hexis-ai/engram-sdk": "^0.5.0",
     "hono": "^4.6.0",
     "zod": "^4.0.0"
   },