@lumetra/engram-ax 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lumetra
+
+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/PRIVACY.md

@@ -0,0 +1,7 @@
+# Privacy
+
+This adapter sends the parameters you (or your agent) pass to its tools — `content`, `query`, `bucket`, `memory_id` — to the Engram REST API at `https://api.lumetra.io` (or the self-hosted base URL you configured). Memories are stored under your Engram tenant, scoped by the API key you supplied when constructing `EngramClient`.
+
+The adapter does not collect, log, or transmit data to any third party other than the Engram service you've explicitly authorized. The adapter does not read other application resources — only the parameters supplied to each tool call.
+
+For Engram's own data-handling and retention policy, see <https://lumetra.io/privacy>.

package/README.md

@@ -0,0 +1,90 @@
+# @lumetra/engram-ax
+
+First-party [Engram](https://lumetra.io) memory adapter for the [`@ax-llm/ax`](https://github.com/ax-llm/ax) agent framework.
+
+Engram is durable, explainable long-term memory for AI agents. This package exposes Engram's REST API as ax-compatible tool definitions you can drop into any `ax()` generator or agent.
+
+## Install
+
+```bash
+npm install @lumetra/engram-ax @ax-llm/ax
+```
+
+## Quick start
+
+```ts
+import { ax, ai } from "@ax-llm/ax";
+import { EngramClient, engramTools } from "@lumetra/engram-ax";
+
+const engram = new EngramClient({
+  apiKey: process.env.ENGRAM_API_KEY!,
+  defaultBucket: "my-app",
+});
+
+const llm = ai({ name: "openai", apiKey: process.env.OPENAI_API_KEY! });
+
+const assistant = ax(
+  "userMessage:string -> reply:string",
+  { functions: engramTools(engram) },
+);
+
+const { reply } = await assistant.forward(llm, {
+  userMessage: "Remember that I prefer dark mode, then tell me what you know about my preferences.",
+});
+
+console.log(reply);
+```
+
+## What you get
+
+`engramTools(client)` returns ax `AxFunction` definitions for:
+
+| Tool            | What it does                                                            |
+|-----------------|-------------------------------------------------------------------------|
+| `store_memory`  | Save a fact / decision / preference to a bucket.                        |
+| `query_memory`  | Retrieve a synthesized answer over memories (semantic + graph search).  |
+
+By default only those two tools are exposed (the destructive ones are footguns when handed to an LLM). Opt in to more if you need them:
+
+```ts
+engramTools(engram, {
+  include: [
+    "store_memory",
+    "query_memory",
+    "list_buckets",
+    "list_memories",
+    "delete_memory",
+    "clear_bucket",
+  ],
+});
+```
+
+## Direct REST client
+
+You can also use the wrapper directly without ax:
+
+```ts
+import { EngramClient } from "@lumetra/engram-ax";
+
+const engram = new EngramClient({ apiKey: process.env.ENGRAM_API_KEY! });
+
+await engram.storeMemory("Jacob prefers dark mode", "prefs");
+const { answer } = await engram.queryMemory("What UI mode does Jacob like?", "prefs");
+```
+
+Methods: `storeMemory`, `queryMemory`, `listBuckets`, `listMemories`, `deleteMemory`, `clearBucket`.
+
+## Configuration
+
+`EngramClient` accepts:
+
+- `apiKey` — your Engram API key (`eng_live_...`). Required.
+- `baseUrl` — defaults to `https://api.lumetra.io`. Override for self-hosted.
+- `defaultBucket` — used when a tool call omits `bucket`. Defaults to `"default"`.
+- `fetch` — optional custom `fetch` implementation.
+
+## License
+
+MIT — Lumetra.
+
+See [PRIVACY.md](./PRIVACY.md).

package/dist/client.d.ts

@@ -0,0 +1,56 @@
+/**
+ * EngramClient — minimal REST wrapper around the Engram memory API.
+ *
+ * Auth: Bearer token (e.g. `eng_live_...`). Base URL defaults to
+ * `https://api.lumetra.io` but can be overridden for self-hosted deployments.
+ */
+export interface EngramClientOptions {
+    /** Engram API key (Bearer token). */
+    apiKey: string;
+    /** Base URL of the Engram API. Defaults to `https://api.lumetra.io`. */
+    baseUrl?: string;
+    /** Default bucket to use when the caller does not specify one. */
+    defaultBucket?: string;
+    /** Optional `fetch` implementation. Defaults to global `fetch`. */
+    fetch?: typeof fetch;
+}
+export interface EngramQueryResponse {
+    success: boolean;
+    answer?: string;
+    [k: string]: unknown;
+}
+export interface EngramBucket {
+    name: string;
+    [k: string]: unknown;
+}
+export interface EngramMemory {
+    id: string;
+    content?: string;
+    [k: string]: unknown;
+}
+export declare class EngramError extends Error {
+    status: number;
+    body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+export declare class EngramClient {
+    readonly baseUrl: string;
+    readonly defaultBucket: string;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    constructor(opts: EngramClientOptions);
+    private request;
+    /** Store a memory in the given bucket. */
+    storeMemory(content: string, bucket?: string): Promise<unknown>;
+    /** Query memories — Engram returns a synthesized `answer` string. */
+    queryMemory(query: string, bucket?: string): Promise<EngramQueryResponse>;
+    /** List buckets on the tenant. */
+    listBuckets(limit?: number, offset?: number): Promise<unknown>;
+    /** List memories in a bucket. */
+    listMemories(bucket?: string, limit?: number): Promise<unknown>;
+    /** Delete a single memory by id. */
+    deleteMemory(memoryId: string, bucket?: string): Promise<unknown>;
+    /** Clear every memory in a bucket. Destructive. */
+    clearBucket(bucket?: string): Promise<unknown>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,mBAAmB;IAClC,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,qBAAa,WAAY,SAAQ,KAAK;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;gBACF,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO;CAM3D;AAED,qBAAa,YAAY;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,IAAI,EAAE,mBAAmB;YAcvB,OAAO;IAsCrB,0CAA0C;IACpC,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAOrE,qEAAqE;IAC/D,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAQ/E,kCAAkC;IAC5B,WAAW,CAAC,KAAK,SAAK,EAAE,MAAM,SAAI,GAAG,OAAO,CAAC,OAAO,CAAC;IAO3D,iCAAiC;IAC3B,YAAY,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,OAAO,CAAC;IAQjE,oCAAoC;IAC9B,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQvE,mDAAmD;IAC7C,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAOrD"}

package/dist/client.js

@@ -0,0 +1,97 @@
+/**
+ * EngramClient — minimal REST wrapper around the Engram memory API.
+ *
+ * Auth: Bearer token (e.g. `eng_live_...`). Base URL defaults to
+ * `https://api.lumetra.io` but can be overridden for self-hosted deployments.
+ */
+export class EngramError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.name = "EngramError";
+        this.status = status;
+        this.body = body;
+    }
+}
+export class EngramClient {
+    baseUrl;
+    defaultBucket;
+    apiKey;
+    fetchImpl;
+    constructor(opts) {
+        if (!opts.apiKey)
+            throw new Error("EngramClient: apiKey is required");
+        this.apiKey = opts.apiKey;
+        this.baseUrl = (opts.baseUrl ?? "https://api.lumetra.io").replace(/\/+$/, "");
+        this.defaultBucket = opts.defaultBucket ?? "default";
+        const f = opts.fetch ?? globalThis.fetch;
+        if (!f) {
+            throw new Error("EngramClient: no fetch implementation available. Pass `fetch` in options or run on Node >=18.");
+        }
+        this.fetchImpl = f.bind(globalThis);
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: "application/json",
+        };
+        if (body !== undefined)
+            headers["Content-Type"] = "application/json";
+        const res = await this.fetchImpl(url, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        const text = await res.text();
+        let parsed = undefined;
+        if (text) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = text;
+            }
+        }
+        if (!res.ok) {
+            throw new EngramError(`Engram ${method} ${path} failed: ${res.status} ${res.statusText}`, res.status, parsed);
+        }
+        return parsed;
+    }
+    /** Store a memory in the given bucket. */
+    async storeMemory(content, bucket) {
+        const b = bucket ?? this.defaultBucket;
+        return this.request("POST", `/v1/buckets/${encodeURIComponent(b)}/memories`, {
+            content,
+        });
+    }
+    /** Query memories — Engram returns a synthesized `answer` string. */
+    async queryMemory(query, bucket) {
+        const b = bucket ?? this.defaultBucket;
+        return this.request("POST", `/v1/query`, {
+            query,
+            bucket: b,
+        });
+    }
+    /** List buckets on the tenant. */
+    async listBuckets(limit = 50, offset = 0) {
+        return this.request("GET", `/v1/buckets?limit=${limit}&offset=${offset}`);
+    }
+    /** List memories in a bucket. */
+    async listMemories(bucket, limit = 50) {
+        const b = bucket ?? this.defaultBucket;
+        return this.request("GET", `/v1/buckets/${encodeURIComponent(b)}/memories?limit=${limit}`);
+    }
+    /** Delete a single memory by id. */
+    async deleteMemory(memoryId, bucket) {
+        const b = bucket ?? this.defaultBucket;
+        return this.request("DELETE", `/v1/buckets/${encodeURIComponent(b)}/memories/${encodeURIComponent(memoryId)}`);
+    }
+    /** Clear every memory in a bucket. Destructive. */
+    async clearBucket(bucket) {
+        const b = bucket ?? this.defaultBucket;
+        return this.request("DELETE", `/v1/buckets/${encodeURIComponent(b)}/memories`);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA8BH,MAAM,OAAO,WAAY,SAAQ,KAAK;IACpC,MAAM,CAAS;IACf,IAAI,CAAU;IACd,YAAY,OAAe,EAAE,MAAc,EAAE,IAAa;QACxD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,MAAM,OAAO,YAAY;IACd,OAAO,CAAS;IAChB,aAAa,CAAS;IACd,MAAM,CAAS;IACf,SAAS,CAAe;IAEzC,YAAY,IAAyB;QACnC,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;QACtE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,OAAO,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,wBAAwB,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAC9E,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,SAAS,CAAC;QACrD,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,IAAK,UAAuC,CAAC,KAAK,CAAC;QACvE,IAAI,CAAC,CAAC,EAAE,CAAC;YACP,MAAM,IAAI,KAAK,CACb,+FAA+F,CAChG,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACtC,CAAC;IAEO,KAAK,CAAC,OAAO,CACnB,MAAc,EACd,IAAY,EACZ,IAAc;QAEd,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,CAAC;QACrC,MAAM,OAAO,GAA2B;YACtC,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE;YACtC,MAAM,EAAE,kBAAkB;SAC3B,CAAC;QACF,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAAC;QAErE,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE;YACpC,MAAM;YACN,OAAO;YACP,IAAI,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;SAC5D,CAAC,CAAC;QAEH,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC9B,IAAI,MAAM,GAAY,SAAS,CAAC;QAChC,IAAI,IAAI,EAAE,CAAC;YACT,IAAI,CAAC;gBACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC5B,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,GAAG,IAAI,CAAC;YAChB,CAAC;QACH,CAAC;QAED,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,WAAW,CACnB,UAAU,MAAM,IAAI,IAAI,YAAY,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,UAAU,EAAE,EAClE,GAAG,CAAC,MAAM,EACV,MAAM,CACP,CAAC;QACJ,CAAC;QACD,OAAO,MAAW,CAAC;IACrB,CAAC;IAED,0CAA0C;IAC1C,KAAK,CAAC,WAAW,CAAC,OAAe,EAAE,MAAe;QAChD,MAAM,CAAC,GAAG,MAAM,IAAI,IAAI,CAAC,aAAa,CAAC;QACvC,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,eAAe,kBAAkB,CAAC,CAAC,CAAC,WAAW,EAAE;YAC3E,OAAO;SACR,CAAC,CAAC;IACL,CAAC;IAED,qEAAqE;IACrE,KAAK,CAAC,WAAW,CAAC,KAAa,EAAE,MAAe;QAC9C,MAAM,CAAC,GAAG,MAAM,IAAI,IAAI,CAAC,aAAa,CAAC;QACvC,OAAO,IAAI,CAAC,OAAO,CAAsB,MAAM,EAAE,WAAW,EAAE;YAC5D,KAAK;YACL,MAAM,EAAE,CAAC;SACV,CAAC,CAAC;IACL,CAAC;IAED,kCAAkC;IAClC,KAAK,CAAC,WAAW,CAAC,KAAK,GAAG,EAAE,EAAE,MAAM,GAAG,CAAC;QACtC,OAAO,IAAI,CAAC,OAAO,CACjB,KAAK,EACL,qBAAqB,KAAK,WAAW,MAAM,EAAE,CAC9C,CAAC;IACJ,CAAC;IAED,iCAAiC;IACjC,KAAK,CAAC,YAAY,CAAC,MAAe,EAAE,KAAK,GAAG,EAAE;QAC5C,MAAM,CAAC,GAAG,MAAM,IAAI,IAAI,CAAC,aAAa,CAAC;QACvC,OAAO,IAAI,CAAC,OAAO,CACjB,KAAK,EACL,eAAe,kBAAkB,CAAC,CAAC,CAAC,mBAAmB,KAAK,EAAE,CAC/D,CAAC;IACJ,CAAC;IAED,oCAAoC;IACpC,KAAK,CAAC,YAAY,CAAC,QAAgB,EAAE,MAAe;QAClD,MAAM,CAAC,GAAG,MAAM,IAAI,IAAI,CAAC,aAAa,CAAC;QACvC,OAAO,IAAI,CAAC,OAAO,CACjB,QAAQ,EACR,eAAe,kBAAkB,CAAC,CAAC,CAAC,aAAa,kBAAkB,CAAC,QAAQ,CAAC,EAAE,CAChF,CAAC;IACJ,CAAC;IAED,mDAAmD;IACnD,KAAK,CAAC,WAAW,CAAC,MAAe;QAC/B,MAAM,CAAC,GAAG,MAAM,IAAI,IAAI,CAAC,aAAa,CAAC;QACvC,OAAO,IAAI,CAAC,OAAO,CACjB,QAAQ,EACR,eAAe,kBAAkB,CAAC,CAAC,CAAC,WAAW,CAChD,CAAC;IACJ,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { EngramClient, EngramError, type EngramClientOptions, type EngramQueryResponse, type EngramBucket, type EngramMemory, } from "./client.js";
+export { engramTools, type EngramAxFunction, type EngramJSONSchemaProperty, type EngramToolsOptions, } from "./tools.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,WAAW,EACX,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,YAAY,GAClB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,WAAW,EACX,KAAK,gBAAgB,EACrB,KAAK,wBAAwB,EAC7B,KAAK,kBAAkB,GACxB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { EngramClient, EngramError, } from "./client.js";
+export { engramTools, } from "./tools.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,WAAW,GAKZ,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,WAAW,GAIZ,MAAM,YAAY,CAAC"}

package/dist/tools.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Ax-compatible tool definitions for Engram.
+ *
+ * These follow the canonical `AxFunction` shape used by `@ax-llm/ax`:
+ *
+ *   { name, description, parameters (JSON Schema), func }
+ *
+ * The shape is intentionally a plain object (rather than the `fn()` builder)
+ * so the package has zero hard dependency on `@ax-llm/ax` — consumers pass
+ * the returned objects straight into `ax(..., { functions })` or
+ * `agent(..., { functions })`.
+ */
+import type { EngramClient } from "./client.js";
+/**
+ * Minimal structural type matching `AxFunction` from `@ax-llm/ax` without
+ * importing it (kept as a peer dep). The real type lives at
+ * `@ax-llm/ax`'s `src/ai/types.ts`.
+ */
+/**
+ * JSON Schema shape compatible with ax's `AxFunctionJSONSchema`.
+ * Each property carries a required `description` (ax enforces this).
+ */
+export interface EngramJSONSchemaProperty {
+    type: string;
+    description: string;
+    enum?: string[];
+    items?: EngramJSONSchemaProperty;
+}
+export interface EngramAxFunction {
+    name: string;
+    description: string;
+    parameters: {
+        type: "object";
+        properties: Record<string, EngramJSONSchemaProperty>;
+        required?: string[];
+    };
+    func: (args?: unknown) => Promise<unknown>;
+}
+export interface EngramToolsOptions {
+    /**
+     * Restrict which Engram tools are exposed to the agent. Defaults to the
+     * two write/read tools (`store_memory`, `query_memory`) since exposing the
+     * destructive ops to an LLM is usually a footgun.
+     */
+    include?: Array<"store_memory" | "query_memory" | "list_buckets" | "list_memories" | "delete_memory" | "clear_bucket">;
+}
+/**
+ * Build ax-compatible tool definitions backed by an `EngramClient`.
+ *
+ * @example
+ * ```ts
+ * import { ax } from "@ax-llm/ax";
+ * import { EngramClient, engramTools } from "@lumetra/engram-ax";
+ *
+ * const client = new EngramClient({ apiKey: process.env.ENGRAM_API_KEY! });
+ * const agent = ax("question:string -> answer:string", {
+ *   functions: engramTools(client),
+ * });
+ * ```
+ */
+export declare function engramTools(client: EngramClient, opts?: EngramToolsOptions): EngramAxFunction[];
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;GAIG;AACH;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,wBAAwB,CAAC;CAClC;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE;QACV,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;QACrD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;IACF,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,OAAO,CAAC,EAAE,KAAK,CACX,cAAc,GACd,cAAc,GACd,cAAc,GACd,eAAe,GACf,eAAe,GACf,cAAc,CACjB,CAAC;CACH;AAOD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,YAAY,EACpB,IAAI,GAAE,kBAAuB,GAC5B,gBAAgB,EAAE,CA8IpB"}

package/dist/tools.js

@@ -0,0 +1,156 @@
+/**
+ * Ax-compatible tool definitions for Engram.
+ *
+ * These follow the canonical `AxFunction` shape used by `@ax-llm/ax`:
+ *
+ *   { name, description, parameters (JSON Schema), func }
+ *
+ * The shape is intentionally a plain object (rather than the `fn()` builder)
+ * so the package has zero hard dependency on `@ax-llm/ax` — consumers pass
+ * the returned objects straight into `ax(..., { functions })` or
+ * `agent(..., { functions })`.
+ */
+const DEFAULT_INCLUDE = [
+    "store_memory",
+    "query_memory",
+];
+/**
+ * Build ax-compatible tool definitions backed by an `EngramClient`.
+ *
+ * @example
+ * ```ts
+ * import { ax } from "@ax-llm/ax";
+ * import { EngramClient, engramTools } from "@lumetra/engram-ax";
+ *
+ * const client = new EngramClient({ apiKey: process.env.ENGRAM_API_KEY! });
+ * const agent = ax("question:string -> answer:string", {
+ *   functions: engramTools(client),
+ * });
+ * ```
+ */
+export function engramTools(client, opts = {}) {
+    const include = new Set(opts.include ?? DEFAULT_INCLUDE);
+    const all = {
+        store_memory: {
+            name: "store_memory",
+            description: "Save a fact, decision, or piece of context to Engram durable memory. " +
+                "Use this when the user shares a fact, preference, or important detail " +
+                "you'll want to recall later.",
+            parameters: {
+                type: "object",
+                properties: {
+                    content: {
+                        type: "string",
+                        description: "The fact or context to remember. One concept per call works best.",
+                    },
+                    bucket: {
+                        type: "string",
+                        description: "Optional bucket name to scope the memory. Defaults to the client's default bucket.",
+                    },
+                },
+                required: ["content"],
+            },
+            func: async (args) => {
+                const { content, bucket } = (args ?? {});
+                if (!content)
+                    throw new Error("store_memory: `content` is required");
+                await client.storeMemory(content, bucket);
+                return { ok: true };
+            },
+        },
+        query_memory: {
+            name: "query_memory",
+            description: "Search Engram durable memory for facts and context relevant to a " +
+                "question. Returns a synthesized answer string. Call this BEFORE " +
+                "answering whenever the user might be referring to prior context.",
+            parameters: {
+                type: "object",
+                properties: {
+                    query: {
+                        type: "string",
+                        description: "Natural-language question to search memory for.",
+                    },
+                    bucket: {
+                        type: "string",
+                        description: "Optional bucket name to search. Defaults to the client's default bucket.",
+                    },
+                },
+                required: ["query"],
+            },
+            func: async (args) => {
+                const { query, bucket } = (args ?? {});
+                if (!query)
+                    throw new Error("query_memory: `query` is required");
+                const res = await client.queryMemory(query, bucket);
+                return { answer: res.answer ?? "", success: res.success ?? true };
+            },
+        },
+        list_buckets: {
+            name: "list_buckets",
+            description: "List Engram memory buckets on the current tenant.",
+            parameters: {
+                type: "object",
+                properties: {
+                    limit: { type: "number", description: "Max buckets to return (default 50)." },
+                    offset: { type: "number", description: "Pagination offset (default 0)." },
+                },
+            },
+            func: async (args) => {
+                const { limit, offset } = (args ?? {});
+                return client.listBuckets(limit, offset);
+            },
+        },
+        list_memories: {
+            name: "list_memories",
+            description: "List recent memories in an Engram bucket.",
+            parameters: {
+                type: "object",
+                properties: {
+                    bucket: { type: "string", description: "Bucket name." },
+                    limit: { type: "number", description: "Max memories to return (default 50)." },
+                },
+            },
+            func: async (args) => {
+                const { bucket, limit } = (args ?? {});
+                return client.listMemories(bucket, limit);
+            },
+        },
+        delete_memory: {
+            name: "delete_memory",
+            description: "Delete a single Engram memory by id. Destructive.",
+            parameters: {
+                type: "object",
+                properties: {
+                    memory_id: { type: "string", description: "Memory id to delete." },
+                    bucket: { type: "string", description: "Bucket the memory lives in." },
+                },
+                required: ["memory_id"],
+            },
+            func: async (args) => {
+                const { memory_id, bucket } = (args ?? {});
+                if (!memory_id)
+                    throw new Error("delete_memory: `memory_id` is required");
+                await client.deleteMemory(memory_id, bucket);
+                return { ok: true };
+            },
+        },
+        clear_bucket: {
+            name: "clear_bucket",
+            description: "Delete EVERY memory in an Engram bucket. Highly destructive — do not " +
+                "call this unless the user has explicitly asked to wipe the bucket.",
+            parameters: {
+                type: "object",
+                properties: {
+                    bucket: { type: "string", description: "Bucket to wipe." },
+                },
+            },
+            func: async (args) => {
+                const { bucket } = (args ?? {});
+                await client.clearBucket(bucket);
+                return { ok: true };
+            },
+        },
+    };
+    return Object.values(all).filter((t) => include.has(t.name));
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA+CH,MAAM,eAAe,GAA+C;IAClE,cAAc;IACd,cAAc;CACf,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CACzB,MAAoB,EACpB,OAA2B,EAAE;IAE7B,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,eAAe,CAAC,CAAC;IAEzD,MAAM,GAAG,GAAqC;QAC5C,YAAY,EAAE;YACZ,IAAI,EAAE,cAAc;YACpB,WAAW,EACT,uEAAuE;gBACvE,wEAAwE;gBACxE,8BAA8B;YAChC,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,OAAO,EAAE;wBACP,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,mEAAmE;qBACjF;oBACD,MAAM,EAAE;wBACN,IAAI,EAAE,QAAQ;wBACd,WAAW,EACT,oFAAoF;qBACvF;iBACF;gBACD,QAAQ,EAAE,CAAC,SAAS,CAAC;aACtB;YACD,IAAI,EAAE,KAAK,EAAE,IAAa,EAAE,EAAE;gBAC5B,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE,CAGtC,CAAC;gBACF,IAAI,CAAC,OAAO;oBAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;gBACrE,MAAM,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;gBAC1C,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;YACtB,CAAC;SACF;QAED,YAAY,EAAE;YACZ,IAAI,EAAE,cAAc;YACpB,WAAW,EACT,mEAAmE;gBACnE,kEAAkE;gBAClE,kEAAkE;YACpE,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,KAAK,EAAE;wBACL,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,iDAAiD;qBAC/D;oBACD,MAAM,EAAE;wBACN,IAAI,EAAE,QAAQ;wBACd,WAAW,EACT,0EAA0E;qBAC7E;iBACF;gBACD,QAAQ,EAAE,CAAC,OAAO,CAAC;aACpB;YACD,IAAI,EAAE,KAAK,EAAE,IAAa,EAAE,EAAE;gBAC5B,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE,CAGpC,CAAC;gBACF,IAAI,CAAC,KAAK;oBAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;gBACjE,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;gBACpD,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,IAAI,EAAE,CAAC;YACpE,CAAC;SACF;QAED,YAAY,EAAE;YACZ,IAAI,EAAE,cAAc;YACpB,WAAW,EAAE,mDAAmD;YAChE,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,qCAAqC,EAAE;oBAC7E,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,gCAAgC,EAAE;iBAC1E;aACF;YACD,IAAI,EAAE,KAAK,EAAE,IAAa,EAAE,EAAE;gBAC5B,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE,CAAwC,CAAC;gBAC9E,OAAO,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YAC3C,CAAC;SACF;QAED,aAAa,EAAE;YACb,IAAI,EAAE,eAAe;YACrB,WAAW,EAAE,2CAA2C;YACxD,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE;oBACvD,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sCAAsC,EAAE;iBAC/E;aACF;YACD,IAAI,EAAE,KAAK,EAAE,IAAa,EAAE,EAAE;gBAC5B,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE,CAAwC,CAAC;gBAC9E,OAAO,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;YAC5C,CAAC;SACF;QAED,aAAa,EAAE;YACb,IAAI,EAAE,eAAe;YACrB,WAAW,EAAE,mDAAmD;YAChE,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sBAAsB,EAAE;oBAClE,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,6BAA6B,EAAE;iBACvE;gBACD,QAAQ,EAAE,CAAC,WAAW,CAAC;aACxB;YACD,IAAI,EAAE,KAAK,EAAE,IAAa,EAAE,EAAE;gBAC5B,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE,CAGxC,CAAC;gBACF,IAAI,CAAC,SAAS;oBAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;gBAC1E,MAAM,MAAM,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;gBAC7C,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;YACtB,CAAC;SACF;QAED,YAAY,EAAE;YACZ,IAAI,EAAE,cAAc;YACpB,WAAW,EACT,uEAAuE;gBACvE,oEAAoE;YACtE,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,iBAAiB,EAAE;iBAC3D;aACF;YACD,IAAI,EAAE,KAAK,EAAE,IAAa,EAAE,EAAE;gBAC5B,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE,CAAwB,CAAC;gBACvD,MAAM,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;gBACjC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;YACtB,CAAC;SACF;KACF,CAAC;IAEF,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAa,CAAC,CAAC,CAAC;AACxE,CAAC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@lumetra/engram-ax",
+  "version": "0.1.0",
+  "description": "Engram memory adapter for the ax (@ax-llm/ax) agent framework.",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "PRIVACY.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "engram",
+    "lumetra",
+    "ax",
+    "ax-llm",
+    "memory",
+    "agent",
+    "llm"
+  ],
+  "author": "Lumetra",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lumetra-io/engram-ax"
+  },
+  "homepage": "https://lumetra.io",
+  "peerDependencies": {
+    "@ax-llm/ax": ">=13.0.0 <16.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@ax-llm/ax": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@ax-llm/ax": "^14.0.0",
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}