@hexis-ai/engram-server 0.4.0 → 0.5.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, 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,8 @@ 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;
     private readonly newPersonId;
     constructor(opts?: InMemoryAdapterOptions);
     createSession(init: SessionInit & {
@@ -39,4 +41,8 @@ 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[]>;
 }

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, 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,8 @@ 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[]>;
 }

package/dist/adapters/postgres.js

@@ -237,6 +237,57 @@ 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);
+    }
 }
 function toPersonInfo(r) {
     const toIso = (v) => (typeof v === "string" ? v : v.toISOString());
@@ -247,3 +298,20 @@ 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),
+    };
+}

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/index.js

@@ -1,4 +1,5 @@
 import * as m0001 from "./0001-baseline";
+import * as m0002 from "./0002-aliases";
 /**
  * Schema migrations, applied in array order. Add a new file under
  * `migrations/NNNN-<slug>.ts` exporting `name` and `sql`, then append it
@@ -6,4 +7,7 @@ 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 },
+];

package/dist/openapi.js

@@ -231,6 +231,32 @@ 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("認証エラー"),
+                },
+            },
+        }),
         "/admin/v1/workspaces": tagged("Workspaces (admin)", {
             post: {
                 summary: "ワークスペースを作成する（デフォルトで初期キーも発行する）。",

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,22 @@ 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/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,11 @@ 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 searchRequestSchema: z.ZodObject<{
     query: z.ZodUnion<readonly [z.ZodObject<{
         sessionId: z.ZodString;

package/dist/schemas.js

@@ -56,6 +56,16 @@ 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(),
+});
 // --- Search ----------------------------------------------------------
 const searchQuerySchema = z.union([
     z.object({ sessionId: z.string().min(1) }),

package/dist/server.js

@@ -58,6 +58,8 @@ 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",
         },
     }));
     app.get("/healthz", (c) => c.json({ ok: true }));
@@ -77,7 +79,8 @@ 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));

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, 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,23 @@ 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[]>;
 }
 /**
  * Pure fold of an event log into the parts a Session needs. Used by adapters

package/openapi.json

@@ -798,6 +798,85 @@
         ]
       }
     },
+    "/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"
+        ]
+      }
+    },
     "/admin/v1/workspaces": {
       "post": {
         "summary": "ワークスペースを作成する（デフォルトで初期キーも発行する）。",

package/package.json

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