@hexis-ai/engram-sdk 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,62 @@
+# @hexis-ai/engram-sdk
+
+Host-side SDK for [engram](https://github.com/hexis-ai/engram). Records agent session steps, buffers them with auto-flush, and exposes a typed search client.
+
+## Install
+
+```bash
+npm i @hexis-ai/engram-sdk
+```
+
+## Usage
+
+```ts
+import { Engram } from "@hexis-ai/engram-sdk";
+
+const engram = new Engram({
+  apiKey: process.env.ENGRAM_API_KEY!,
+  baseUrl: process.env.ENGRAM_BASE_URL!,
+});
+
+// 1. Begin a session — id can be your own conversation id.
+const session = await engram.startSession({ id: conversationId, channel: "chat_ui" });
+
+// 2. Record steps as the agent runs. The SDK extracts canonical resource
+//    references from common MCP / built-in tools (WebFetch, WebSearch,
+//    Linear, Notion, ...) when you pass `input` + `result`.
+session.recordStep({ tool: "WebFetch", input: { url }, result });
+
+// Or pass resources directly:
+session.recordStep({ tool: "Read", resources: ["file:src/x.ts"] });
+
+// 3. Optional metadata.
+session.addParticipant("slack:U001");
+session.setTitle("debug auth flake");
+
+// 4. Flush at session end.
+await session.end();
+
+// 5. Search later.
+const { results } = await engram.search({ query: { sessionId: conversationId } });
+```
+
+## Configuration
+
+| Option | Default | Notes |
+|---|---|---|
+| `apiKey` | required | sent as `Authorization: Bearer <key>` |
+| `baseUrl` | required | engram-server URL |
+| `flushIntervalMs` | 2000 | 0 to disable auto-flush |
+| `batchSize` | 32 | flushes immediately when buffer reaches this |
+| `onError` | `console.error` | called on transport errors |
+| `fetch` | `globalThis.fetch` | inject for testing |
+
+## Resource normalization
+
+Tool names like `mcp__linear__list_issues` are stripped to bare `list_issues`. Resources are encoded as `service:resource_id` (e.g. `linear:HEX-1`, `web:https://...`, `notion:<pageId>`).
+
+The extraction logic is exposed via `@hexis-ai/engram-sdk/extract` for hosts that want to derive resources without going through the SDK.
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,97 @@
+import type { ScoredSession, SearchOptions, Session, SessionStep } from "@hexis-ai/engram-core";
+import { type RefCandidate } from "./extract";
+import type { EventBatch, SessionInit } from "./types";
+export interface EngramOptions {
+    apiKey: string;
+    baseUrl: string;
+    fetch?: typeof fetch;
+    /**
+     * Auto-flush events at most this many ms after the first buffered event.
+     * Default 2000. Set to 0 to disable auto-flush (manual `flush()` only).
+     */
+    flushIntervalMs?: number;
+    /**
+     * Auto-flush when the buffer reaches this size. Default 32.
+     */
+    batchSize?: number;
+    /** Hook invoked on transport errors. Default: console.error. */
+    onError?: (err: unknown) => void;
+}
+export interface RecordStepInput {
+    tool: string;
+    /** Engram-format resources (`service:id`). Used as-is when provided. */
+    resources?: string[];
+    /**
+     * If `resources` is omitted, the SDK runs `extractReferences()` over
+     * `input` + `result` to derive resources automatically.
+     */
+    input?: Record<string, unknown>;
+    result?: unknown;
+    /** Override vendor extraction (otherwise inferred via `parseToolName`). */
+    vendor?: string;
+    /** Pre-resolved bare tool name (otherwise inferred via `parseToolName`). */
+    bareName?: string;
+}
+export interface SearchRequest {
+    /**
+     * Either an existing session id (server-side fetch + use as query) or an
+     * inline `Session`. Inline is convenient for one-off / synthetic queries.
+     */
+    query: {
+        sessionId: string;
+    } | {
+        session: Pick<Session, "steps" | "participants">;
+    };
+    options?: SearchOptions;
+}
+export interface SearchResponse {
+    results: ScoredSession[];
+}
+export declare class Engram {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly flushIntervalMs;
+    private readonly batchSize;
+    private readonly onError;
+    constructor(opts: EngramOptions);
+    /** Begin a new session. Returns a handle for buffering events. */
+    startSession(init?: SessionInit): Promise<EngramSession>;
+    /** Fetch a single Session by id. */
+    getSession(id: string): Promise<Session>;
+    /** List recent sessions (server defines defaults & limits). */
+    listSessions(opts?: {
+        limit?: number;
+        channel?: string;
+    }): Promise<Session[]>;
+    /** Run a search. */
+    search(req: SearchRequest): Promise<SearchResponse>;
+    /** Internal: ship an event batch to the server. */
+    sendBatch(sessionId: string, batch: EventBatch): Promise<void>;
+    /** Internal accessor used by EngramSession to honor SDK config. */
+    get config(): {
+        flushIntervalMs: number;
+        batchSize: number;
+        onError: (err: unknown) => void;
+    };
+    private request;
+}
+export declare class EngramSession {
+    readonly id: string;
+    private readonly engram;
+    private readonly buffer;
+    private seq;
+    private flushTimer;
+    private inFlight;
+    private ended;
+    constructor(engram: Engram, id: string);
+    recordStep(input: RecordStepInput): SessionStep;
+    addParticipant(identityRef: string): void;
+    setTitle(title: string): void;
+    /** Mark the session ended and flush buffered events. */
+    end(): Promise<void>;
+    /** Force a flush regardless of batch size / timer. */
+    flush(): Promise<void>;
+    private enqueue;
+}
+export type { RefCandidate };

package/dist/client.js

@@ -0,0 +1,184 @@
+import { encodeResourceId, extractReferences } from "./extract";
+import { parseToolName } from "./tool-name";
+export class Engram {
+    apiKey;
+    baseUrl;
+    fetchImpl;
+    flushIntervalMs;
+    batchSize;
+    onError;
+    constructor(opts) {
+        if (!opts.apiKey)
+            throw new Error("Engram: apiKey is required");
+        if (!opts.baseUrl)
+            throw new Error("Engram: baseUrl is required");
+        this.apiKey = opts.apiKey;
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
+        this.flushIntervalMs = opts.flushIntervalMs ?? 2000;
+        this.batchSize = opts.batchSize ?? 32;
+        this.onError = opts.onError ?? ((e) => console.error("[engram]", e));
+    }
+    /** Begin a new session. Returns a handle for buffering events. */
+    async startSession(init = {}) {
+        const ack = await this.request("POST", "/v1/sessions", init);
+        return new EngramSession(this, ack.id);
+    }
+    /** Fetch a single Session by id. */
+    async getSession(id) {
+        return this.request("GET", `/v1/sessions/${encodeURIComponent(id)}`);
+    }
+    /** List recent sessions (server defines defaults & limits). */
+    async listSessions(opts = {}) {
+        const qs = new URLSearchParams();
+        if (opts.limit !== undefined)
+            qs.set("limit", String(opts.limit));
+        if (opts.channel)
+            qs.set("channel", opts.channel);
+        const tail = qs.toString();
+        return this.request("GET", `/v1/sessions${tail ? `?${tail}` : ""}`);
+    }
+    /** Run a search. */
+    async search(req) {
+        return this.request("POST", "/v1/search", req);
+    }
+    /** Internal: ship an event batch to the server. */
+    async sendBatch(sessionId, batch) {
+        if (batch.events.length === 0)
+            return;
+        await this.request("POST", `/v1/sessions/${encodeURIComponent(sessionId)}/events`, batch);
+    }
+    /** Internal accessor used by EngramSession to honor SDK config. */
+    get config() {
+        return { flushIntervalMs: this.flushIntervalMs, batchSize: this.batchSize, onError: this.onError };
+    }
+    async request(method, path, body) {
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method,
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${this.apiKey}`,
+            },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`engram ${method} ${path} ${res.status}: ${text}`);
+        }
+        if (res.status === 204)
+            return undefined;
+        const ct = res.headers.get("content-type") ?? "";
+        if (!ct.includes("application/json"))
+            return undefined;
+        return (await res.json());
+    }
+}
+export class EngramSession {
+    id;
+    engram;
+    buffer = [];
+    seq = 0;
+    flushTimer = null;
+    inFlight = null;
+    ended = false;
+    constructor(engram, id) {
+        this.engram = engram;
+        this.id = id;
+    }
+    recordStep(input) {
+        const resources = resolveResources(input);
+        const tool = input.bareName ?? parseToolName(input.tool).bareName;
+        const ev = {
+            type: "step",
+            seq: this.seq++,
+            at: new Date().toISOString(),
+            tool,
+            resources,
+        };
+        this.enqueue(ev);
+        return { tool, resources };
+    }
+    addParticipant(identityRef) {
+        const ev = {
+            type: "participant",
+            seq: this.seq++,
+            at: new Date().toISOString(),
+            identityRef,
+        };
+        this.enqueue(ev);
+    }
+    setTitle(title) {
+        const ev = {
+            type: "title",
+            seq: this.seq++,
+            at: new Date().toISOString(),
+            title,
+        };
+        this.enqueue(ev);
+    }
+    /** Mark the session ended and flush buffered events. */
+    async end() {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.enqueue({
+            type: "end",
+            seq: this.seq++,
+            at: new Date().toISOString(),
+        });
+        await this.flush();
+    }
+    /** Force a flush regardless of batch size / timer. */
+    async flush() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        if (this.inFlight)
+            await this.inFlight;
+        if (this.buffer.length === 0)
+            return;
+        const events = this.buffer.splice(0);
+        this.inFlight = this.engram
+            .sendBatch(this.id, { events })
+            .catch((e) => {
+            this.engram.config.onError(e);
+            this.buffer.unshift(...events);
+            throw e;
+        })
+            .finally(() => {
+            this.inFlight = null;
+        });
+        await this.inFlight;
+    }
+    enqueue(ev) {
+        this.buffer.push(ev);
+        const { batchSize, flushIntervalMs } = this.engram.config;
+        if (this.buffer.length >= batchSize) {
+            void this.flush().catch(() => { });
+            return;
+        }
+        if (flushIntervalMs > 0 && !this.flushTimer) {
+            this.flushTimer = setTimeout(() => {
+                this.flushTimer = null;
+                void this.flush().catch(() => { });
+            }, flushIntervalMs);
+        }
+    }
+}
+function resolveResources(input) {
+    if (input.resources)
+        return [...input.resources];
+    if (input.input === undefined && input.result === undefined)
+        return [];
+    const { vendor, bareName } = (() => {
+        if (input.bareName !== undefined)
+            return { vendor: input.vendor, bareName: input.bareName };
+        return parseToolName(input.tool);
+    })();
+    const refs = extractReferences(vendor, bareName, input.input ?? {}, input.result);
+    return dedupe(refs.map(encodeResourceId));
+}
+function dedupe(xs) {
+    return [...new Set(xs)];
+}

package/dist/extract.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Resource extraction: derives engram-shaped resource references from a
+ * single tool call's `(name, input, result)` triple.
+ *
+ * Migrated from monet's `agent/reference-extractor.ts` so that any host that
+ * speaks Claude Agent SDK / vendored MCP can normalize tool calls without
+ * shipping its own copy.
+ *
+ * Resource id format follows engram convention: `${service}:${id-or-url}`.
+ */
+export type ReferenceService = "linear" | "notion" | "web" | "github";
+export type ReferenceAction = "read" | "write";
+export interface RefCandidate {
+    service: ReferenceService;
+    action: ReferenceAction;
+    resource_id: string;
+    title?: string;
+    url?: string;
+}
+export declare function extractReferences(vendor: string | undefined, toolName: string, input: Record<string, unknown>, result: unknown): RefCandidate[];
+/** Convenience: encode RefCandidate to engram resource id (`service:resource_id`). */
+export declare function encodeResourceId(ref: Pick<RefCandidate, "service" | "resource_id">): string;

package/dist/extract.js

@@ -0,0 +1,137 @@
+/**
+ * Resource extraction: derives engram-shaped resource references from a
+ * single tool call's `(name, input, result)` triple.
+ *
+ * Migrated from monet's `agent/reference-extractor.ts` so that any host that
+ * speaks Claude Agent SDK / vendored MCP can normalize tool calls without
+ * shipping its own copy.
+ *
+ * Resource id format follows engram convention: `${service}:${id-or-url}`.
+ */
+const isWebSearch = (n) => n === "WebSearch" || n === "web_search";
+const isWebFetch = (n) => n === "WebFetch" || n === "web_fetch";
+const WRITE_TOOLS = {
+    create_issue: "write",
+    update_issue: "write",
+    "notion-create-pages": "write",
+    "notion-update-page": "write",
+    "notion-create-database": "write",
+    "notion-create-comment": "write",
+};
+function getAction(toolName) {
+    return WRITE_TOOLS[toolName] ?? "read";
+}
+function extractMcpText(result) {
+    const r = result;
+    if (!r?.content)
+        return "";
+    return r.content
+        .filter((c) => c.type === "text" && c.text)
+        .map((c) => c.text)
+        .join("\n");
+}
+function tryParseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+export function extractReferences(vendor, toolName, input, result) {
+    if (vendor === undefined) {
+        if (toolName === "create_issue" || toolName === "update_issue") {
+            return extractNativeLinearIssueRef(toolName, result);
+        }
+        if (isWebSearch(toolName) || isWebFetch(toolName))
+            return extractWebRefs(toolName, input);
+        return [];
+    }
+    if (vendor === "linear")
+        return extractLinearRefs(toolName, input, result);
+    if (vendor === "notion")
+        return extractNotionRefs(toolName, input, result);
+    return [];
+}
+/** Convenience: encode RefCandidate to engram resource id (`service:resource_id`). */
+export function encodeResourceId(ref) {
+    return `${ref.service}:${ref.resource_id}`;
+}
+function extractNativeLinearIssueRef(toolName, result) {
+    if (!result || typeof result !== "object")
+        return [];
+    const obj = result;
+    if (typeof obj.id !== "string" && typeof obj.identifier !== "string")
+        return [];
+    return [{
+            service: "linear",
+            action: getAction(toolName),
+            resource_id: String(obj.identifier ?? obj.id),
+            title: obj.title,
+            url: obj.url,
+        }];
+}
+function extractLinearRefs(toolName, input, result) {
+    const action = getAction(toolName);
+    const text = extractMcpText(result);
+    const parsed = tryParseJson(text);
+    if (parsed && typeof parsed === "object" && "id" in parsed) {
+        const obj = parsed;
+        return [{
+                service: "linear",
+                action,
+                resource_id: String(obj.identifier ?? obj.id),
+                title: obj.title,
+                url: obj.url,
+            }];
+    }
+    if (parsed && typeof parsed === "object" && "issues" in parsed) {
+        const issues = parsed.issues;
+        return issues.map((issue) => ({
+            service: "linear",
+            action: "read",
+            resource_id: String(issue.identifier ?? issue.id),
+            title: issue.title,
+            url: issue.url,
+        }));
+    }
+    if (input.issue_id) {
+        return [{ service: "linear", action, resource_id: String(input.issue_id) }];
+    }
+    return [];
+}
+function extractNotionRefs(toolName, input, result) {
+    const action = getAction(toolName);
+    if (input.pageId) {
+        return [{ service: "notion", action, resource_id: String(input.pageId) }];
+    }
+    const text = extractMcpText(result);
+    const urlMatches = text.match(/https:\/\/www\.notion\.so\/[^\s)">]+/g);
+    if (urlMatches) {
+        return urlMatches.slice(0, 5).map((url) => ({
+            service: "notion",
+            action,
+            resource_id: url,
+            url,
+        }));
+    }
+    return [];
+}
+function extractWebRefs(toolName, input) {
+    if (isWebFetch(toolName) && input.url) {
+        return [{
+                service: "web",
+                action: "read",
+                resource_id: String(input.url),
+                url: String(input.url),
+            }];
+    }
+    if (isWebSearch(toolName) && input.query) {
+        return [{
+                service: "web",
+                action: "read",
+                resource_id: `search:${String(input.query)}`,
+            }];
+    }
+    return [];
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { Engram, EngramSession, type EngramOptions, type RecordStepInput, type SearchRequest, type SearchResponse, } from "./client";
+export { extractReferences, encodeResourceId, type RefCandidate, type ReferenceService, type ReferenceAction, } from "./extract";
+export { parseToolName, type ParsedToolName } from "./tool-name";
+export type { SessionInit, SessionAck, SessionEvent, StepEvent, ParticipantEvent, TitleEvent, EndEvent, EventBatch, } from "./types";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { Engram, EngramSession, } from "./client";
+export { extractReferences, encodeResourceId, } from "./extract";
+export { parseToolName } from "./tool-name";

package/dist/tool-name.d.ts

@@ -0,0 +1,12 @@
+/**
+ * MCP tool names follow the convention `mcp__<server>__<bare>` when invoked
+ * via the Claude Agent SDK / Anthropic SDK. The "in-process engram MCP server"
+ * (server name "engram") is collapsed to no vendor since it is conceptually
+ * native to the host. Built-in SDK tools (Read, Edit, WebSearch, ...) come in
+ * with no prefix at all.
+ */
+export interface ParsedToolName {
+    vendor?: string;
+    bareName: string;
+}
+export declare function parseToolName(name: string): ParsedToolName;

package/dist/tool-name.js

@@ -0,0 +1,10 @@
+const MCP_RE = /^mcp__([^_]+)__(.+)$/;
+export function parseToolName(name) {
+    const m = MCP_RE.exec(name);
+    if (!m)
+        return { bareName: name };
+    const [, server, bare] = m;
+    if (server === "engram")
+        return { bareName: bare };
+    return { vendor: server, bareName: bare };
+}

package/dist/types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Wire types shared between @hexis-ai/engram-sdk and @hexis-ai/engram-server.
+ *
+ * Keep this file dependency-free (no @hexis-ai/engram-core import) so it can be reused
+ * by language ports later. Algorithm types live in @hexis-ai/engram-core.
+ */
+export interface SessionInit {
+    /** Optional client-supplied id; server may accept or override. */
+    id?: string;
+    title?: string;
+    /**
+     * Free-form classification of where this session originated
+     * (e.g. `chat_ui`, `slack_dm`, `cron:dailyDigest`).
+     */
+    channel?: string;
+    participants?: string[];
+}
+export interface SessionAck {
+    id: string;
+}
+export interface StepEvent {
+    type: "step";
+    seq: number;
+    at: string;
+    tool: string;
+    resources: string[];
+}
+export interface ParticipantEvent {
+    type: "participant";
+    seq: number;
+    at: string;
+    identityRef: string;
+}
+export interface TitleEvent {
+    type: "title";
+    seq: number;
+    at: string;
+    title: string;
+}
+export interface EndEvent {
+    type: "end";
+    seq: number;
+    at: string;
+}
+export type SessionEvent = StepEvent | ParticipantEvent | TitleEvent | EndEvent;
+export interface EventBatch {
+    events: SessionEvent[];
+}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Wire types shared between @hexis-ai/engram-sdk and @hexis-ai/engram-server.
+ *
+ * Keep this file dependency-free (no @hexis-ai/engram-core import) so it can be reused
+ * by language ports later. Algorithm types live in @hexis-ai/engram-core.
+ */
+export {};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@hexis-ai/engram-sdk",
+  "version": "0.1.0",
+  "description": "Host SDK for engram. Records agent session steps and ships them to an engram server.",
+  "keywords": ["engram", "agents", "claude", "anthropic", "sdk", "observability"],
+  "homepage": "https://github.com/hexis-ai/engram#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hexis-ai/engram.git",
+    "directory": "packages/sdk"
+  },
+  "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"
+    },
+    "./extract": {
+      "types": "./dist/extract.d.ts",
+      "default": "./dist/extract.js"
+    },
+    "./tool-name": {
+      "types": "./dist/tool-name.d.ts",
+      "default": "./dist/tool-name.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"
+  },
+  "dependencies": {
+    "@hexis-ai/engram-core": "workspace:*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}