@hexis-ai/engram-sdk

Host-side SDK for engram. Records agent session steps, buffers them with auto-flush, and exposes a typed search client.

Install

npm i @hexis-ai/engram-sdk

Usage

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