@hexis-ai/engram-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hexis ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# @hexis-ai/engram-server
+
+Hono-based HTTP server for engram with pluggable storage.
+
+## Install
+
+```bash
+npm i @hexis-ai/engram-server
+# optional, for the postgres adapter:
+npm i postgres
+```
+
+## Quick start
+
+```ts
+import { createServer, InMemoryAdapter } from "@hexis-ai/engram-server";
+
+const adapter = new InMemoryAdapter();
+const app = createServer({
+  auth: (apiKey) => apiKey === process.env.ENGRAM_API_KEY
+    ? { workspaceId: "default", storage: adapter }
+    : null,
+});
+
+export default { port: 3100, fetch: app.fetch };
+```
+
+## With Postgres
+
+```ts
+import postgres from "postgres";
+import { createServer, PostgresAdapter } from "@hexis-ai/engram-server";
+
+const sql = postgres(process.env.DATABASE_URL!);
+
+// Multi-tenant: one adapter instance per workspace, scoped by workspaceId.
+function adapterFor(workspaceId: string) {
+  return new PostgresAdapter({ workspaceId, sql });
+}
+
+await new PostgresAdapter({ workspaceId: "_init", sql }).ensureSchema();
+
+const app = createServer({
+  auth: async (apiKey) => {
+    const ws = await resolveApiKey(apiKey);    // your own keying
+    if (!ws) return null;
+    return { workspaceId: ws, storage: adapterFor(ws) };
+  },
+});
+```
+
+## Routes
+
+```
+POST   /v1/sessions             { id?, title?, channel?, participants? } → { id }
+POST   /v1/sessions/:id/events  { events: SessionEvent[] }                → 204
+GET    /v1/sessions/:id                                                   → Session
+GET    /v1/sessions?limit&channel                                         → Session[]
+POST   /v1/search               { query, options? }                       → { results }
+```
+
+## Storage adapter contract
+
+Implement `StorageAdapter` to plug in your own backend (SQLite, Redis, Dynamo, etc.):
+
+```ts
+interface StorageAdapter {
+  createSession(init): Promise<void>;
+  appendEvents(sessionId, events): Promise<void>;
+  getSession(sessionId): Promise<Session | null>;
+  listSessions({ limit, channel? }): Promise<Session[]>;
+}
+```
+
+Events are append-only and idempotent on `(sessionId, seq)`. Sessions materialize via the `foldEvents()` helper.
+
+## License
+
+MIT

package/dist/adapters/memory.d.ts

@@ -0,0 +1,20 @@
+import type { Session } from "@hexis-ai/engram-core";
+import type { SessionEvent, SessionInit } from "@hexis-ai/engram-sdk";
+import { type StorageAdapter } from "../storage";
+/**
+ * In-process storage adapter for tests, dev, and small single-node deploys.
+ * Idempotency: events keyed by (sessionId, seq) — duplicates overwrite by seq.
+ */
+export declare class InMemoryAdapter implements StorageAdapter {
+    private readonly sessions;
+    createSession(init: SessionInit & {
+        id: string;
+        createdAt: string;
+    }): Promise<void>;
+    appendEvents(sessionId: string, events: SessionEvent[]): Promise<void>;
+    getSession(sessionId: string): Promise<Session | null>;
+    listSessions(opts: {
+        limit: number;
+        channel?: string;
+    }): Promise<Session[]>;
+}

package/dist/adapters/memory.js

@@ -0,0 +1,49 @@
+import { foldEvents } from "../storage";
+/**
+ * In-process storage adapter for tests, dev, and small single-node deploys.
+ * Idempotency: events keyed by (sessionId, seq) — duplicates overwrite by seq.
+ */
+export class InMemoryAdapter {
+    sessions = new Map();
+    async createSession(init) {
+        if (this.sessions.has(init.id))
+            return;
+        this.sessions.set(init.id, {
+            row: {
+                id: init.id,
+                ...(init.title ? { title: init.title } : {}),
+                ...(init.channel ? { channel: init.channel } : {}),
+                participants: init.participants ?? [],
+                createdAt: init.createdAt,
+            },
+            events: new Map(),
+        });
+    }
+    async appendEvents(sessionId, events) {
+        const s = this.sessions.get(sessionId);
+        if (!s)
+            throw new Error(`session not found: ${sessionId}`);
+        for (const ev of events)
+            s.events.set(ev.seq, ev);
+    }
+    async getSession(sessionId) {
+        const s = this.sessions.get(sessionId);
+        if (!s)
+            return null;
+        return foldEvents(s.row, [...s.events.values()], new Date());
+    }
+    async listSessions(opts) {
+        const now = new Date();
+        const all = [];
+        for (const stored of this.sessions.values()) {
+            if (opts.channel && stored.row.channel !== opts.channel)
+                continue;
+            all.push({
+                s: foldEvents(stored.row, [...stored.events.values()], now),
+                createdAt: stored.row.createdAt,
+            });
+        }
+        all.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+        return all.slice(0, opts.limit).map((x) => x.s);
+    }
+}

package/dist/adapters/postgres.d.ts

@@ -0,0 +1,38 @@
+import type { Session } from "@hexis-ai/engram-core";
+import type { SessionEvent, SessionInit } from "@hexis-ai/engram-sdk";
+import { type StorageAdapter } from "../storage";
+/**
+ * Minimal subset of `postgres` driver's tagged-template surface that this
+ * adapter relies on. Declared structurally so the package does not hard-import
+ * the `postgres` module (it is a peer dep) and tests can supply a fake.
+ */
+export interface SqlClient {
+    <T = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]>;
+}
+export interface PostgresAdapterOptions {
+    /** Workspace scope baked into every row. Required for multi-tenant isolation. */
+    workspaceId: string;
+    sql: SqlClient;
+}
+export declare class PostgresAdapter implements StorageAdapter {
+    private readonly workspaceId;
+    private readonly sql;
+    constructor(opts: PostgresAdapterOptions);
+    /**
+     * Create the schema. Call once at boot. Safe to invoke repeatedly.
+     * Postgres pg-tag template clients accept multi-statement strings via
+     * `sql.unsafe()` in the real driver; for portability we issue them
+     * separately so any tagged-template impl works.
+     */
+    ensureSchema(): Promise<void>;
+    createSession(init: SessionInit & {
+        id: string;
+        createdAt: string;
+    }): Promise<void>;
+    appendEvents(sessionId: string, events: SessionEvent[]): Promise<void>;
+    getSession(sessionId: string): Promise<Session | null>;
+    listSessions(opts: {
+        limit: number;
+        channel?: string;
+    }): Promise<Session[]>;
+}

package/dist/adapters/postgres.js

@@ -0,0 +1,116 @@
+import { foldEvents } from "../storage";
+const SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS engram_sessions (
+  workspace_id  TEXT      NOT NULL,
+  id            TEXT      NOT NULL,
+  title         TEXT,
+  channel       TEXT,
+  participants  TEXT[]    NOT NULL DEFAULT '{}',
+  created_at    TIMESTAMPTZ NOT NULL,
+  PRIMARY KEY (workspace_id, id)
+);
+
+CREATE TABLE IF NOT EXISTS engram_events (
+  workspace_id TEXT NOT NULL,
+  session_id   TEXT NOT NULL,
+  seq          INTEGER NOT NULL,
+  type         TEXT NOT NULL,
+  at           TIMESTAMPTZ NOT NULL,
+  payload      JSONB NOT NULL,
+  PRIMARY KEY (workspace_id, session_id, seq),
+  FOREIGN KEY (workspace_id, session_id)
+    REFERENCES engram_sessions(workspace_id, id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_engram_sessions_workspace_created
+  ON engram_sessions (workspace_id, created_at DESC);
+`;
+export class PostgresAdapter {
+    workspaceId;
+    sql;
+    constructor(opts) {
+        this.workspaceId = opts.workspaceId;
+        this.sql = opts.sql;
+    }
+    /**
+     * Create the schema. Call once at boot. Safe to invoke repeatedly.
+     * Postgres pg-tag template clients accept multi-statement strings via
+     * `sql.unsafe()` in the real driver; for portability we issue them
+     * separately so any tagged-template impl works.
+     */
+    async ensureSchema() {
+        const stmts = SCHEMA_SQL.split(/;\s*\n/).map((s) => s.trim()).filter(Boolean);
+        for (const stmt of stmts) {
+            // Tagged-template invocation with no interpolations.
+            await this.sql([stmt + ";"]);
+        }
+    }
+    async createSession(init) {
+        await this.sql `
+      INSERT INTO engram_sessions (workspace_id, id, title, channel, participants, created_at)
+      VALUES (
+        ${this.workspaceId},
+        ${init.id},
+        ${init.title ?? null},
+        ${init.channel ?? null},
+        ${init.participants ?? []},
+        ${init.createdAt}
+      )
+      ON CONFLICT (workspace_id, id) DO NOTHING
+    `;
+    }
+    async appendEvents(sessionId, events) {
+        if (events.length === 0)
+            return;
+        for (const ev of events) {
+            await this.sql `
+        INSERT INTO engram_events (workspace_id, session_id, seq, type, at, payload)
+        VALUES (
+          ${this.workspaceId},
+          ${sessionId},
+          ${ev.seq},
+          ${ev.type},
+          ${ev.at},
+          ${JSON.stringify(ev)}::jsonb
+        )
+        ON CONFLICT (workspace_id, session_id, seq) DO NOTHING
+      `;
+        }
+    }
+    async getSession(sessionId) {
+        const rows = await this.sql `
+      SELECT id, title, channel, participants, created_at
+      FROM engram_sessions
+      WHERE workspace_id = ${this.workspaceId} AND id = ${sessionId}
+      LIMIT 1
+    `;
+        if (rows.length === 0)
+            return null;
+        const r = rows[0];
+        const events = await this.sql `
+      SELECT payload FROM engram_events
+      WHERE workspace_id = ${this.workspaceId} AND session_id = ${sessionId}
+      ORDER BY seq
+    `;
+        const row = {
+            id: r.id,
+            ...(r.title ? { title: r.title } : {}),
+            ...(r.channel ? { channel: r.channel } : {}),
+            participants: r.participants,
+            createdAt: typeof r.created_at === "string" ? r.created_at : r.created_at.toISOString(),
+        };
+        return foldEvents(row, events.map((e) => e.payload), new Date());
+    }
+    async listSessions(opts) {
+        const channelFilter = opts.channel ?? null;
+        const rows = await this.sql `
+      SELECT id FROM engram_sessions
+      WHERE workspace_id = ${this.workspaceId}
+        AND (${channelFilter}::text IS NULL OR channel = ${channelFilter}::text)
+      ORDER BY created_at DESC
+      LIMIT ${opts.limit}
+    `;
+        const sessions = await Promise.all(rows.map((r) => this.getSession(r.id)));
+        return sessions.filter((s) => s !== null);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createServer, type CreateServerOptions, type AuthResolver, type WorkspaceContext, } from "./server";
+export { foldEvents, type StorageAdapter, type SessionRow, } from "./storage";
+export { InMemoryAdapter } from "./adapters/memory";
+export { PostgresAdapter, type PostgresAdapterOptions, type SqlClient, } from "./adapters/postgres";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createServer, } from "./server";
+export { foldEvents, } from "./storage";
+export { InMemoryAdapter } from "./adapters/memory";
+export { PostgresAdapter, } from "./adapters/postgres";

package/dist/server.d.ts

@@ -0,0 +1,35 @@
+import { Hono } from "hono";
+import type { StorageAdapter } from "./storage";
+/**
+ * Resolve an API key (raw `Authorization: Bearer <key>` token) into a
+ * workspace context. Throwing or returning null short-circuits to 401.
+ */
+export interface AuthResolver {
+    (apiKey: string): Promise<WorkspaceContext | null> | WorkspaceContext | null;
+}
+export interface WorkspaceContext {
+    workspaceId: string;
+    /** The storage adapter scoped to this workspace. */
+    storage: StorageAdapter;
+}
+export interface CreateServerOptions {
+    /** Resolves Bearer tokens into workspace contexts. */
+    auth: AuthResolver;
+    /**
+     * Generates session ids. Defaults to `crypto.randomUUID()`.
+     * Provide a custom function for deterministic ids in tests.
+     */
+    newSessionId?: () => string;
+    /**
+     * Clamps for `GET /v1/sessions?limit=…`. Defaults: 100 / 500.
+     */
+    defaultListLimit?: number;
+    maxListLimit?: number;
+}
+interface Env {
+    Variables: {
+        ctx: WorkspaceContext;
+    };
+}
+export declare function createServer(opts: CreateServerOptions): Hono<Env>;
+export {};

package/dist/server.js

@@ -0,0 +1,93 @@
+import { Hono } from "hono";
+import { buildIndex, search, } from "@hexis-ai/engram-core";
+export function createServer(opts) {
+    const newId = opts.newSessionId ?? (() => crypto.randomUUID());
+    const defaultLimit = opts.defaultListLimit ?? 100;
+    const maxLimit = opts.maxListLimit ?? 500;
+    const app = new Hono();
+    app.use("/v1/*", async (c, next) => {
+        const auth = c.req.header("authorization");
+        const m = auth?.match(/^Bearer\s+(.+)$/i);
+        if (!m)
+            return c.json({ error: "unauthorized" }, 401);
+        const ctx = await opts.auth(m[1]);
+        if (!ctx)
+            return c.json({ error: "unauthorized" }, 401);
+        c.set("ctx", ctx);
+        await next();
+    });
+    app.post("/v1/sessions", async (c) => {
+        const body = (await c.req.json().catch(() => null));
+        if (body === null)
+            return c.json({ error: "invalid_json" }, 400);
+        const id = body.id ?? newId();
+        const createdAt = new Date().toISOString();
+        await c.var.ctx.storage.createSession({
+            ...body,
+            id,
+            createdAt,
+        });
+        return c.json({ id });
+    });
+    app.post("/v1/sessions/:id/events", async (c) => {
+        const id = c.req.param("id");
+        const body = (await c.req.json().catch(() => null));
+        if (!body || !Array.isArray(body.events)) {
+            return c.json({ error: "events_array_required" }, 400);
+        }
+        try {
+            await c.var.ctx.storage.appendEvents(id, body.events);
+        }
+        catch (e) {
+            return c.json({ error: "session_not_found", message: e.message }, 404);
+        }
+        return c.body(null, 204);
+    });
+    app.get("/v1/sessions/:id", async (c) => {
+        const id = c.req.param("id");
+        const s = await c.var.ctx.storage.getSession(id);
+        if (!s)
+            return c.json({ error: "session_not_found" }, 404);
+        return c.json(s);
+    });
+    app.get("/v1/sessions", async (c) => {
+        const limit = clampLimit(c, defaultLimit, maxLimit);
+        const channel = c.req.query("channel") || undefined;
+        const sessions = await c.var.ctx.storage.listSessions({ limit, channel });
+        return c.json(sessions);
+    });
+    app.post("/v1/search", async (c) => {
+        const body = (await c.req.json().catch(() => null));
+        if (!body || !body.query)
+            return c.json({ error: "query_required" }, 400);
+        const corpus = await c.var.ctx.storage.listSessions({ limit: maxLimit });
+        let queryQuery;
+        if ("sessionId" in body.query) {
+            const q = await c.var.ctx.storage.getSession(body.query.sessionId);
+            if (!q)
+                return c.json({ error: "query_session_not_found" }, 404);
+            queryQuery = q;
+        }
+        else {
+            queryQuery = body.query.session;
+        }
+        const index = buildIndex(corpus);
+        const opts = body.options ?? {};
+        const queryParticipants = opts.queryParticipants ?? queryQuery.participants ?? [];
+        const results = search(queryQuery.steps, index, {
+            ...opts,
+            queryParticipants,
+        });
+        return c.json({ results });
+    });
+    return app;
+}
+function clampLimit(c, def, max) {
+    const raw = c.req.query("limit");
+    if (!raw)
+        return def;
+    const n = parseInt(raw, 10);
+    if (isNaN(n) || n < 1)
+        return def;
+    return Math.min(n, max);
+}

package/dist/storage.d.ts

@@ -0,0 +1,35 @@
+import type { Session } from "@hexis-ai/engram-core";
+import type { SessionEvent, SessionInit } from "@hexis-ai/engram-sdk";
+/**
+ * Storage adapter interface. Each implementation owns persistence for
+ * a single workspace's sessions. Multi-tenancy is the host's concern: the
+ * server keys adapters by workspace id (derived from API key).
+ */
+export interface StorageAdapter {
+    /** Create a session row. Returns the assigned id. */
+    createSession(init: SessionInit & {
+        id: string;
+        createdAt: string;
+    }): Promise<void>;
+    /** Append events for a session in batch. Idempotent on (sessionId, seq). */
+    appendEvents(sessionId: string, events: SessionEvent[]): Promise<void>;
+    /** Materialize a session (events folded into Session shape). */
+    getSession(sessionId: string): Promise<Session | null>;
+    /** List recent sessions. */
+    listSessions(opts: {
+        limit: number;
+        channel?: string;
+    }): Promise<Session[]>;
+}
+/**
+ * Pure fold of an event log into the parts a Session needs. Used by adapters
+ * after they retrieve raw events to assemble the materialized view.
+ */
+export interface SessionRow {
+    id: string;
+    title?: string;
+    channel?: string;
+    participants: string[];
+    createdAt: string;
+}
+export declare function foldEvents(row: SessionRow, events: SessionEvent[], now: Date): Session;

package/dist/storage.js

@@ -0,0 +1,26 @@
+export function foldEvents(row, events, now) {
+    const sorted = [...events].sort((a, b) => a.seq - b.seq);
+    const steps = [];
+    const participants = new Set(row.participants);
+    let title = row.title;
+    for (const ev of sorted) {
+        if (ev.type === "step") {
+            steps.push({ tool: ev.tool, resources: [...ev.resources] });
+        }
+        else if (ev.type === "participant") {
+            participants.add(ev.identityRef);
+        }
+        else if (ev.type === "title") {
+            title = ev.title;
+        }
+    }
+    const created = new Date(row.createdAt).getTime();
+    const daysAgo = Math.max(0, (now.getTime() - created) / 86_400_000);
+    return {
+        id: row.id,
+        ...(title ? { title } : {}),
+        steps,
+        daysAgo,
+        ...(participants.size > 0 ? { participants: [...participants] } : {}),
+    };
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@hexis-ai/engram-server",
+  "version": "0.1.0",
+  "description": "Engram server: ingest agent session events, persist via a pluggable adapter, expose search.",
+  "keywords": ["engram", "agents", "search", "hono", "postgres", "server"],
+  "homepage": "https://github.com/hexis-ai/engram#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hexis-ai/engram.git",
+    "directory": "packages/server"
+  },
+  "bugs": "https://github.com/hexis-ai/engram/issues",
+  "author": "hexis ltd.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./adapters/memory": {
+      "types": "./dist/adapters/memory.d.ts",
+      "default": "./dist/adapters/memory.js"
+    },
+    "./adapters/postgres": {
+      "types": "./dist/adapters/postgres.d.ts",
+      "default": "./dist/adapters/postgres.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepack": "bun run build",
+    "pack": "bun run build && bun pm pack",
+    "test": "bun test",
+    "type-check": "tsc --noEmit",
+    "dev": "bun --hot src/dev.ts"
+  },
+  "dependencies": {
+    "@hexis-ai/engram-core": "workspace:*",
+    "@hexis-ai/engram-sdk": "workspace:*",
+    "hono": "^4.6.0"
+  },
+  "peerDependencies": {
+    "postgres": "^3.4.0"
+  },
+  "peerDependenciesMeta": {
+    "postgres": { "optional": true }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}