@hexis-ai/engram-server

Hono-based HTTP server for engram with pluggable storage.

Install

npm i @hexis-ai/engram-server
# optional, for the postgres adapter:
npm i postgres

Quick start

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

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.):

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