@lumetra/engram 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/README.md

@@ -0,0 +1,106 @@
+# @lumetra/engram
+
+Official TypeScript client for [Engram](https://lumetra.io) — durable, explainable memory for AI agents.
+
+- Zero runtime dependencies (uses built-in `fetch`).
+- ESM + CommonJS, full `.d.ts` typings.
+- Node 18+, Bun, Deno, edge runtimes.
+
+## Install
+
+```bash
+npm install @lumetra/engram
+# or
+yarn add @lumetra/engram
+# or
+pnpm add @lumetra/engram
+```
+
+## Quickstart
+
+```ts
+import { EngramClient } from '@lumetra/engram';
+
+const engram = new EngramClient({
+  apiKey: process.env.ENGRAM_API_KEY, // or set ENGRAM_API_KEY and omit
+});
+
+// Store a fact
+await engram.storeMemory('User prefers dark mode.', 'user-123');
+
+// Recall — returns a synthesized answer plus the memories that contributed
+const result = await engram.query('What are this user\'s UI preferences?', {
+  buckets: ['user-123'],
+});
+
+console.log(result.answer);
+console.log(result.explanation?.retrieved_memories);
+```
+
+## Configuration
+
+```ts
+new EngramClient({
+  apiKey: 'eng_live_...',           // or ENGRAM_API_KEY env var
+  baseUrl: 'https://api.lumetra.io', // or ENGRAM_BASE_URL env var
+  timeoutMs: 30_000,                 // optional, default 30s
+  fetch: customFetch,                // optional, defaults to globalThis.fetch
+});
+```
+
+> **BYOK reminder.** Engram is bring-your-own-key end-to-end. Configure an OpenAI / Anthropic / Groq / Together / Fireworks key on the [Lumetra portal](https://lumetra.io/models) before your first call, or `storeMemory` / `query` will return HTTP 412.
+
+## API surface
+
+### Memories
+- `storeMemory(content, bucket?)` — store a single fact
+- `storeMemories(contents[], bucket?)` — batched store
+- `listMemories(bucket?, { limit?, offset? })` — paginated list
+- `deleteMemory(memoryId, bucket?)` — delete one memory
+- `clearMemories(bucket)` — delete every memory in a bucket
+
+### Query
+- `query(question, { buckets?, topK?, skipSynthesis?, returnExplanation? })`
+  - `buckets` fuses across multiple buckets in one call
+  - `skipSynthesis: true` returns retrieval-only — no server-side LLM call
+  - response shape: `{ answer, explanation: { retrieved_memories, profile, graph_facts }, usage }`
+
+### Buckets
+- `listBuckets()` — all buckets in your tenant
+- `createBucket(name, description?)`
+- `deleteBucket(bucket)`
+
+### Profile
+- `getProfile(bucket?)` — the canonical profile prepended to recall
+- `regenerateProfile(bucket?)` — rebuild from current memories
+
+### Errors
+
+All HTTP failures throw `EngramError`:
+
+```ts
+import { EngramError } from '@lumetra/engram';
+
+try {
+  await engram.storeMemory('...');
+} catch (err) {
+  if (err instanceof EngramError) {
+    console.error(err.status, err.body);
+  }
+}
+```
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm run build       # emits dist/
+npm run dev         # watch mode
+```
+
+`npm run prepublishOnly` runs typecheck + clean build automatically when publishing.
+
+## License
+
+[MIT](LICENSE) — Copyright (c) 2026 Lumetra.

package/dist/index.cjs

@@ -0,0 +1,171 @@
+'use strict';
+
+// src/types.ts
+var EngramError = class extends Error {
+  name = "EngramError";
+  status;
+  body;
+  constructor(message, status, body) {
+    super(message);
+    this.status = status;
+    this.body = body;
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.lumetra.io";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var EngramClient = class {
+  apiKey;
+  baseUrl;
+  fetchImpl;
+  timeoutMs;
+  constructor(options = {}) {
+    const apiKey = options.apiKey ?? (typeof process !== "undefined" ? process.env?.ENGRAM_API_KEY : void 0) ?? "";
+    if (!apiKey) {
+      throw new Error(
+        "EngramClient: apiKey is required. Pass it explicitly or set ENGRAM_API_KEY in your environment."
+      );
+    }
+    const baseUrl = options.baseUrl ?? (typeof process !== "undefined" ? process.env?.ENGRAM_BASE_URL : void 0) ?? DEFAULT_BASE_URL;
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    if (typeof this.fetchImpl !== "function") {
+      throw new Error(
+        "EngramClient: no fetch implementation available. Use Node 18+, or pass options.fetch."
+      );
+    }
+  }
+  async request(path, init = {
+    method: "GET"
+  }) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    if (init.query) {
+      for (const [k, v] of Object.entries(init.query)) {
+        if (v !== void 0) url.searchParams.set(k, String(v));
+      }
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let res;
+    try {
+      res = await this.fetchImpl(url.toString(), {
+        method: init.method,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json"
+        },
+        body: init.body !== void 0 ? JSON.stringify(init.body) : void 0,
+        signal: controller.signal
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    const text = await res.text();
+    let parsed = void 0;
+    if (text) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        parsed = text;
+      }
+    }
+    if (!res.ok) {
+      const detail = parsed && typeof parsed === "object" && parsed !== null && "error" in parsed ? parsed.error : parsed;
+      throw new EngramError(
+        `Engram API ${res.status}: ${typeof detail === "string" ? detail : JSON.stringify(detail ?? "")}`,
+        res.status,
+        parsed
+      );
+    }
+    return parsed;
+  }
+  // ---------- Memories ----------
+  async storeMemory(content, bucket = "default") {
+    return this.request(
+      `/v1/buckets/${encodeURIComponent(bucket)}/memories`,
+      { method: "POST", body: { content } }
+    );
+  }
+  async storeMemories(contents, bucket = "default") {
+    return this.request(
+      `/v1/buckets/${encodeURIComponent(bucket)}/memories`,
+      { method: "POST", body: { memories: contents.map((content) => ({ content })) } }
+    );
+  }
+  async listMemories(bucket = "default", options = {}) {
+    return this.request(
+      `/v1/buckets/${encodeURIComponent(bucket)}/memories`,
+      {
+        method: "GET",
+        query: { limit: options.limit ?? 20, offset: options.offset ?? 0 }
+      }
+    );
+  }
+  async deleteMemory(memoryId, bucket = "default") {
+    await this.request(
+      `/v1/buckets/${encodeURIComponent(bucket)}/memories/${encodeURIComponent(memoryId)}`,
+      { method: "DELETE" }
+    );
+  }
+  async clearMemories(bucket) {
+    await this.request(
+      `/v1/buckets/${encodeURIComponent(bucket)}/memories`,
+      { method: "DELETE" }
+    );
+  }
+  // ---------- Query ----------
+  async query(question, options = {}) {
+    const buckets = options.buckets ?? ["default"];
+    return this.request("/v1/query", {
+      method: "POST",
+      body: {
+        query: question,
+        buckets,
+        options: {
+          top_k: options.topK ?? 8,
+          return_explanation: options.returnExplanation ?? true,
+          skip_synthesis: options.skipSynthesis ?? false
+        }
+      }
+    });
+  }
+  // ---------- Buckets ----------
+  async listBuckets() {
+    const result = await this.request(`/v1/buckets`, {
+      method: "GET"
+    });
+    return Array.isArray(result) ? result : result.buckets;
+  }
+  async createBucket(name, description) {
+    return this.request("/v1/buckets", {
+      method: "POST",
+      body: { name, description }
+    });
+  }
+  async deleteBucket(bucket) {
+    await this.request(`/v1/buckets/${encodeURIComponent(bucket)}`, {
+      method: "DELETE"
+    });
+  }
+  // ---------- Profile ----------
+  async getProfile(bucket = "default") {
+    return this.request(
+      `/v1/buckets/${encodeURIComponent(bucket)}/profile`,
+      { method: "GET" }
+    );
+  }
+  async regenerateProfile(bucket = "default") {
+    return this.request(
+      `/v1/buckets/${encodeURIComponent(bucket)}/profile/regenerate`,
+      { method: "POST" }
+    );
+  }
+};
+
+exports.EngramClient = EngramClient;
+exports.EngramError = EngramError;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/client.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["export interface EngramClientOptions {\n  /**\n   * Engram API key. Looks like `eng_live_...`. Defaults to `process.env.ENGRAM_API_KEY`.\n   */\n  apiKey?: string;\n  /**\n   * API base URL. Defaults to `process.env.ENGRAM_BASE_URL` or `https://api.lumetra.io`.\n   */\n  baseUrl?: string;\n  /**\n   * Custom fetch implementation. Defaults to the global `fetch`.\n   * Useful for proxying, retry middleware, or non-Node runtimes.\n   */\n  fetch?: typeof fetch;\n  /**\n   * Request timeout in milliseconds. Defaults to 30000 (30s).\n   */\n  timeoutMs?: number;\n}\n\nexport interface Bucket {\n  id: string;\n  name: string;\n  description?: string | null;\n  created_at: string;\n  memory_count?: number;\n}\n\nexport interface Memory {\n  id: string;\n  content: string;\n  bucket_name?: string;\n  created_at?: string;\n  token_count?: number;\n}\n\nexport interface StoreMemoryResult {\n  id: string;\n  bucket_name: string;\n  token_count: number;\n}\n\nexport interface RetrievedMemory {\n  id?: string;\n  content: string;\n  score?: number;\n  bucket?: string;\n}\n\nexport interface QueryExplanation {\n  retrieved_memories?: RetrievedMemory[];\n  profile?: string | null;\n  graph_facts?: string[];\n}\n\nexport interface QueryUsage {\n  prompt_tokens?: number;\n  completion_tokens?: number;\n  total_tokens?: number;\n}\n\nexport interface QueryResult {\n  answer: string;\n  explanation?: QueryExplanation;\n  usage?: QueryUsage;\n}\n\nexport interface QueryOptions {\n  /**\n   * Buckets to fuse across. Defaults to `['default']`.\n   */\n  buckets?: string[];\n  /**\n   * Maximum number of memories to retrieve. Defaults to 8.\n   */\n  topK?: number;\n  /**\n   * If true, server skips the synthesis LLM call and returns retrieval-only.\n   * `answer` will be an empty string in that case. Defaults to false.\n   */\n  skipSynthesis?: boolean;\n  /**\n   * Whether to populate the `explanation` field. Defaults to true.\n   */\n  returnExplanation?: boolean;\n}\n\nexport interface ListMemoriesOptions {\n  limit?: number;\n  offset?: number;\n}\n\nexport interface ListMemoriesResult {\n  memories: Memory[];\n  total: number;\n  limit: number;\n  offset: number;\n}\n\nexport class EngramError extends Error {\n  override readonly name = 'EngramError';\n  readonly status: number;\n  readonly body: unknown;\n\n  constructor(message: string, status: number, body: unknown) {\n    super(message);\n    this.status = status;\n    this.body = body;\n  }\n}\n","import {\n  EngramError,\n  type Bucket,\n  type EngramClientOptions,\n  type ListMemoriesOptions,\n  type ListMemoriesResult,\n  type QueryOptions,\n  type QueryResult,\n  type StoreMemoryResult,\n} from './types.js';\n\nconst DEFAULT_BASE_URL = 'https://api.lumetra.io';\nconst DEFAULT_TIMEOUT_MS = 30_000;\n\nexport class EngramClient {\n  private readonly apiKey: string;\n  private readonly baseUrl: string;\n  private readonly fetchImpl: typeof fetch;\n  private readonly timeoutMs: number;\n\n  constructor(options: EngramClientOptions = {}) {\n    const apiKey =\n      options.apiKey ??\n      (typeof process !== 'undefined' ? process.env?.ENGRAM_API_KEY : undefined) ??\n      '';\n    if (!apiKey) {\n      throw new Error(\n        'EngramClient: apiKey is required. Pass it explicitly or set ENGRAM_API_KEY in your environment.',\n      );\n    }\n    const baseUrl =\n      options.baseUrl ??\n      (typeof process !== 'undefined' ? process.env?.ENGRAM_BASE_URL : undefined) ??\n      DEFAULT_BASE_URL;\n\n    this.apiKey = apiKey;\n    this.baseUrl = baseUrl.replace(/\\/+$/, '');\n    this.fetchImpl = options.fetch ?? globalThis.fetch;\n    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n\n    if (typeof this.fetchImpl !== 'function') {\n      throw new Error(\n        'EngramClient: no fetch implementation available. Use Node 18+, or pass options.fetch.',\n      );\n    }\n  }\n\n  private async request<T>(\n    path: string,\n    init: { method: string; body?: unknown; query?: Record<string, string | number | undefined> } = {\n      method: 'GET',\n    },\n  ): Promise<T> {\n    const url = new URL(`${this.baseUrl}${path}`);\n    if (init.query) {\n      for (const [k, v] of Object.entries(init.query)) {\n        if (v !== undefined) url.searchParams.set(k, String(v));\n      }\n    }\n\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), this.timeoutMs);\n\n    let res: Response;\n    try {\n      res = await this.fetchImpl(url.toString(), {\n        method: init.method,\n        headers: {\n          Authorization: `Bearer ${this.apiKey}`,\n          'Content-Type': 'application/json',\n        },\n        body: init.body !== undefined ? JSON.stringify(init.body) : undefined,\n        signal: controller.signal,\n      });\n    } finally {\n      clearTimeout(timer);\n    }\n\n    const text = await res.text();\n    let parsed: unknown = undefined;\n    if (text) {\n      try {\n        parsed = JSON.parse(text);\n      } catch {\n        parsed = text;\n      }\n    }\n\n    if (!res.ok) {\n      const detail =\n        parsed && typeof parsed === 'object' && parsed !== null && 'error' in parsed\n          ? (parsed as { error: unknown }).error\n          : parsed;\n      throw new EngramError(\n        `Engram API ${res.status}: ${typeof detail === 'string' ? detail : JSON.stringify(detail ?? '')}`,\n        res.status,\n        parsed,\n      );\n    }\n\n    return parsed as T;\n  }\n\n  // ---------- Memories ----------\n\n  async storeMemory(content: string, bucket: string = 'default'): Promise<StoreMemoryResult> {\n    return this.request<StoreMemoryResult>(\n      `/v1/buckets/${encodeURIComponent(bucket)}/memories`,\n      { method: 'POST', body: { content } },\n    );\n  }\n\n  async storeMemories(\n    contents: string[],\n    bucket: string = 'default',\n  ): Promise<{ memories: StoreMemoryResult[] }> {\n    return this.request<{ memories: StoreMemoryResult[] }>(\n      `/v1/buckets/${encodeURIComponent(bucket)}/memories`,\n      { method: 'POST', body: { memories: contents.map((content) => ({ content })) } },\n    );\n  }\n\n  async listMemories(\n    bucket: string = 'default',\n    options: ListMemoriesOptions = {},\n  ): Promise<ListMemoriesResult> {\n    return this.request<ListMemoriesResult>(\n      `/v1/buckets/${encodeURIComponent(bucket)}/memories`,\n      {\n        method: 'GET',\n        query: { limit: options.limit ?? 20, offset: options.offset ?? 0 },\n      },\n    );\n  }\n\n  async deleteMemory(memoryId: string, bucket: string = 'default'): Promise<void> {\n    await this.request<unknown>(\n      `/v1/buckets/${encodeURIComponent(bucket)}/memories/${encodeURIComponent(memoryId)}`,\n      { method: 'DELETE' },\n    );\n  }\n\n  async clearMemories(bucket: string): Promise<void> {\n    await this.request<unknown>(\n      `/v1/buckets/${encodeURIComponent(bucket)}/memories`,\n      { method: 'DELETE' },\n    );\n  }\n\n  // ---------- Query ----------\n\n  async query(question: string, options: QueryOptions = {}): Promise<QueryResult> {\n    const buckets = options.buckets ?? ['default'];\n    return this.request<QueryResult>('/v1/query', {\n      method: 'POST',\n      body: {\n        query: question,\n        buckets,\n        options: {\n          top_k: options.topK ?? 8,\n          return_explanation: options.returnExplanation ?? true,\n          skip_synthesis: options.skipSynthesis ?? false,\n        },\n      },\n    });\n  }\n\n  // ---------- Buckets ----------\n\n  async listBuckets(): Promise<Bucket[]> {\n    const result = await this.request<{ buckets: Bucket[] } | Bucket[]>(`/v1/buckets`, {\n      method: 'GET',\n    });\n    return Array.isArray(result) ? result : result.buckets;\n  }\n\n  async createBucket(name: string, description?: string): Promise<Bucket> {\n    return this.request<Bucket>('/v1/buckets', {\n      method: 'POST',\n      body: { name, description },\n    });\n  }\n\n  async deleteBucket(bucket: string): Promise<void> {\n    await this.request<unknown>(`/v1/buckets/${encodeURIComponent(bucket)}`, {\n      method: 'DELETE',\n    });\n  }\n\n  // ---------- Profile ----------\n\n  async getProfile(bucket: string = 'default'): Promise<{ profile: string | null }> {\n    return this.request<{ profile: string | null }>(\n      `/v1/buckets/${encodeURIComponent(bucket)}/profile`,\n      { method: 'GET' },\n    );\n  }\n\n  async regenerateProfile(bucket: string = 'default'): Promise<{ profile: string | null }> {\n    return this.request<{ profile: string | null }>(\n      `/v1/buckets/${encodeURIComponent(bucket)}/profile/regenerate`,\n      { method: 'POST' },\n    );\n  }\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,122 @@
+interface EngramClientOptions {
+    /**
+     * Engram API key. Looks like `eng_live_...`. Defaults to `process.env.ENGRAM_API_KEY`.
+     */
+    apiKey?: string;
+    /**
+     * API base URL. Defaults to `process.env.ENGRAM_BASE_URL` or `https://api.lumetra.io`.
+     */
+    baseUrl?: string;
+    /**
+     * Custom fetch implementation. Defaults to the global `fetch`.
+     * Useful for proxying, retry middleware, or non-Node runtimes.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Request timeout in milliseconds. Defaults to 30000 (30s).
+     */
+    timeoutMs?: number;
+}
+interface Bucket {
+    id: string;
+    name: string;
+    description?: string | null;
+    created_at: string;
+    memory_count?: number;
+}
+interface Memory {
+    id: string;
+    content: string;
+    bucket_name?: string;
+    created_at?: string;
+    token_count?: number;
+}
+interface StoreMemoryResult {
+    id: string;
+    bucket_name: string;
+    token_count: number;
+}
+interface RetrievedMemory {
+    id?: string;
+    content: string;
+    score?: number;
+    bucket?: string;
+}
+interface QueryExplanation {
+    retrieved_memories?: RetrievedMemory[];
+    profile?: string | null;
+    graph_facts?: string[];
+}
+interface QueryUsage {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    total_tokens?: number;
+}
+interface QueryResult {
+    answer: string;
+    explanation?: QueryExplanation;
+    usage?: QueryUsage;
+}
+interface QueryOptions {
+    /**
+     * Buckets to fuse across. Defaults to `['default']`.
+     */
+    buckets?: string[];
+    /**
+     * Maximum number of memories to retrieve. Defaults to 8.
+     */
+    topK?: number;
+    /**
+     * If true, server skips the synthesis LLM call and returns retrieval-only.
+     * `answer` will be an empty string in that case. Defaults to false.
+     */
+    skipSynthesis?: boolean;
+    /**
+     * Whether to populate the `explanation` field. Defaults to true.
+     */
+    returnExplanation?: boolean;
+}
+interface ListMemoriesOptions {
+    limit?: number;
+    offset?: number;
+}
+interface ListMemoriesResult {
+    memories: Memory[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+declare class EngramError extends Error {
+    readonly name = "EngramError";
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+
+declare class EngramClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(options?: EngramClientOptions);
+    private request;
+    storeMemory(content: string, bucket?: string): Promise<StoreMemoryResult>;
+    storeMemories(contents: string[], bucket?: string): Promise<{
+        memories: StoreMemoryResult[];
+    }>;
+    listMemories(bucket?: string, options?: ListMemoriesOptions): Promise<ListMemoriesResult>;
+    deleteMemory(memoryId: string, bucket?: string): Promise<void>;
+    clearMemories(bucket: string): Promise<void>;
+    query(question: string, options?: QueryOptions): Promise<QueryResult>;
+    listBuckets(): Promise<Bucket[]>;
+    createBucket(name: string, description?: string): Promise<Bucket>;
+    deleteBucket(bucket: string): Promise<void>;
+    getProfile(bucket?: string): Promise<{
+        profile: string | null;
+    }>;
+    regenerateProfile(bucket?: string): Promise<{
+        profile: string | null;
+    }>;
+}
+
+export { type Bucket, EngramClient, type EngramClientOptions, EngramError, type ListMemoriesOptions, type ListMemoriesResult, type Memory, type QueryExplanation, type QueryOptions, type QueryResult, type QueryUsage, type RetrievedMemory, type StoreMemoryResult };

package/dist/index.d.ts

@@ -0,0 +1,122 @@
+interface EngramClientOptions {
+    /**
+     * Engram API key. Looks like `eng_live_...`. Defaults to `process.env.ENGRAM_API_KEY`.
+     */
+    apiKey?: string;
+    /**
+     * API base URL. Defaults to `process.env.ENGRAM_BASE_URL` or `https://api.lumetra.io`.
+     */
+    baseUrl?: string;
+    /**
+     * Custom fetch implementation. Defaults to the global `fetch`.
+     * Useful for proxying, retry middleware, or non-Node runtimes.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Request timeout in milliseconds. Defaults to 30000 (30s).
+     */
+    timeoutMs?: number;
+}
+interface Bucket {
+    id: string;
+    name: string;
+    description?: string | null;
+    created_at: string;
+    memory_count?: number;
+}
+interface Memory {
+    id: string;
+    content: string;
+    bucket_name?: string;
+    created_at?: string;
+    token_count?: number;
+}
+interface StoreMemoryResult {
+    id: string;
+    bucket_name: string;
+    token_count: number;
+}
+interface RetrievedMemory {
+    id?: string;
+    content: string;
+    score?: number;
+    bucket?: string;
+}
+interface QueryExplanation {
+    retrieved_memories?: RetrievedMemory[];
+    profile?: string | null;
+    graph_facts?: string[];
+}
+interface QueryUsage {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    total_tokens?: number;
+}
+interface QueryResult {
+    answer: string;
+    explanation?: QueryExplanation;
+    usage?: QueryUsage;
+}
+interface QueryOptions {
+    /**
+     * Buckets to fuse across. Defaults to `['default']`.
+     */
+    buckets?: string[];
+    /**
+     * Maximum number of memories to retrieve. Defaults to 8.
+     */
+    topK?: number;
+    /**
+     * If true, server skips the synthesis LLM call and returns retrieval-only.
+     * `answer` will be an empty string in that case. Defaults to false.
+     */
+    skipSynthesis?: boolean;
+    /**
+     * Whether to populate the `explanation` field. Defaults to true.
+     */
+    returnExplanation?: boolean;
+}
+interface ListMemoriesOptions {
+    limit?: number;
+    offset?: number;
+}
+interface ListMemoriesResult {
+    memories: Memory[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+declare class EngramError extends Error {
+    readonly name = "EngramError";
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+
+declare class EngramClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(options?: EngramClientOptions);
+    private request;
+    storeMemory(content: string, bucket?: string): Promise<StoreMemoryResult>;
+    storeMemories(contents: string[], bucket?: string): Promise<{
+        memories: StoreMemoryResult[];
+    }>;
+    listMemories(bucket?: string, options?: ListMemoriesOptions): Promise<ListMemoriesResult>;
+    deleteMemory(memoryId: string, bucket?: string): Promise<void>;
+    clearMemories(bucket: string): Promise<void>;
+    query(question: string, options?: QueryOptions): Promise<QueryResult>;
+    listBuckets(): Promise<Bucket[]>;
+    createBucket(name: string, description?: string): Promise<Bucket>;
+    deleteBucket(bucket: string): Promise<void>;
+    getProfile(bucket?: string): Promise<{
+        profile: string | null;
+    }>;
+    regenerateProfile(bucket?: string): Promise<{
+        profile: string | null;
+    }>;
+}
+
+export { type Bucket, EngramClient, type EngramClientOptions, EngramError, type ListMemoriesOptions, type ListMemoriesResult, type Memory, type QueryExplanation, type QueryOptions, type QueryResult, type QueryUsage, type RetrievedMemory, type StoreMemoryResult };

package/dist/index.js

@@ -0,0 +1,168 @@
+// src/types.ts
+var EngramError = class extends Error {
+  name = "EngramError";
+  status;
+  body;
+  constructor(message, status, body) {
+    super(message);
+    this.status = status;
+    this.body = body;
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.lumetra.io";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var EngramClient = class {
+  apiKey;
+  baseUrl;
+  fetchImpl;
+  timeoutMs;
+  constructor(options = {}) {
+    const apiKey = options.apiKey ?? (typeof process !== "undefined" ? process.env?.ENGRAM_API_KEY : void 0) ?? "";
+    if (!apiKey) {
+      throw new Error(
+        "EngramClient: apiKey is required. Pass it explicitly or set ENGRAM_API_KEY in your environment."
+      );
+    }
+    const baseUrl = options.baseUrl ?? (typeof process !== "undefined" ? process.env?.ENGRAM_BASE_URL : void 0) ?? DEFAULT_BASE_URL;
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    if (typeof this.fetchImpl !== "function") {
+      throw new Error(
+        "EngramClient: no fetch implementation available. Use Node 18+, or pass options.fetch."
+      );
+    }
+  }
+  async request(path, init = {
+    method: "GET"
+  }) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    if (init.query) {
+      for (const [k, v] of Object.entries(init.query)) {
+        if (v !== void 0) url.searchParams.set(k, String(v));
+      }
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let res;
+    try {
+      res = await this.fetchImpl(url.toString(), {
+        method: init.method,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json"
+        },
+        body: init.body !== void 0 ? JSON.stringify(init.body) : void 0,
+        signal: controller.signal
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    const text = await res.text();
+    let parsed = void 0;
+    if (text) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        parsed = text;
+      }
+    }
+    if (!res.ok) {
+      const detail = parsed && typeof parsed === "object" && parsed !== null && "error" in parsed ? parsed.error : parsed;
+      throw new EngramError(
+        `Engram API ${res.status}: ${typeof detail === "string" ? detail : JSON.stringify(detail ?? "")}`,
+        res.status,
+        parsed
+      );
+    }
+    return parsed;
+  }
+  // ---------- Memories ----------
+  async storeMemory(content, bucket = "default") {
+    return this.request(
+      `/v1/buckets/${encodeURIComponent(bucket)}/memories`,
+      { method: "POST", body: { content } }
+    );
+  }
+  async storeMemories(contents, bucket = "default") {
+    return this.request(
+      `/v1/buckets/${encodeURIComponent(bucket)}/memories`,
+      { method: "POST", body: { memories: contents.map((content) => ({ content })) } }
+    );
+  }
+  async listMemories(bucket = "default", options = {}) {
+    return this.request(
+      `/v1/buckets/${encodeURIComponent(bucket)}/memories`,
+      {
+        method: "GET",
+        query: { limit: options.limit ?? 20, offset: options.offset ?? 0 }
+      }
+    );
+  }
+  async deleteMemory(memoryId, bucket = "default") {
+    await this.request(
+      `/v1/buckets/${encodeURIComponent(bucket)}/memories/${encodeURIComponent(memoryId)}`,
+      { method: "DELETE" }
+    );
+  }
+  async clearMemories(bucket) {
+    await this.request(
+      `/v1/buckets/${encodeURIComponent(bucket)}/memories`,
+      { method: "DELETE" }
+    );
+  }
+  // ---------- Query ----------
+  async query(question, options = {}) {
+    const buckets = options.buckets ?? ["default"];
+    return this.request("/v1/query", {
+      method: "POST",
+      body: {
+        query: question,
+        buckets,
+        options: {
+          top_k: options.topK ?? 8,
+          return_explanation: options.returnExplanation ?? true,
+          skip_synthesis: options.skipSynthesis ?? false
+        }
+      }
+    });
+  }
+  // ---------- Buckets ----------
+  async listBuckets() {
+    const result = await this.request(`/v1/buckets`, {
+      method: "GET"
+    });
+    return Array.isArray(result) ? result : result.buckets;
+  }
+  async createBucket(name, description) {
+    return this.request("/v1/buckets", {
+      method: "POST",
+      body: { name, description }
+    });
+  }
+  async deleteBucket(bucket) {
+    await this.request(`/v1/buckets/${encodeURIComponent(bucket)}`, {
+      method: "DELETE"
+    });
+  }
+  // ---------- Profile ----------
+  async getProfile(bucket = "default") {
+    return this.request(
+      `/v1/buckets/${encodeURIComponent(bucket)}/profile`,
+      { method: "GET" }
+    );
+  }
+  async regenerateProfile(bucket = "default") {
+    return this.request(
+      `/v1/buckets/${encodeURIComponent(bucket)}/profile/regenerate`,
+      { method: "POST" }
+    );
+  }
+};
+
+export { EngramClient, EngramError };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/client.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["export interface EngramClientOptions {\n  /**\n   * Engram API key. Looks like `eng_live_...`. Defaults to `process.env.ENGRAM_API_KEY`.\n   */\n  apiKey?: string;\n  /**\n   * API base URL. Defaults to `process.env.ENGRAM_BASE_URL` or `https://api.lumetra.io`.\n   */\n  baseUrl?: string;\n  /**\n   * Custom fetch implementation. Defaults to the global `fetch`.\n   * Useful for proxying, retry middleware, or non-Node runtimes.\n   */\n  fetch?: typeof fetch;\n  /**\n   * Request timeout in milliseconds. Defaults to 30000 (30s).\n   */\n  timeoutMs?: number;\n}\n\nexport interface Bucket {\n  id: string;\n  name: string;\n  description?: string | null;\n  created_at: string;\n  memory_count?: number;\n}\n\nexport interface Memory {\n  id: string;\n  content: string;\n  bucket_name?: string;\n  created_at?: string;\n  token_count?: number;\n}\n\nexport interface StoreMemoryResult {\n  id: string;\n  bucket_name: string;\n  token_count: number;\n}\n\nexport interface RetrievedMemory {\n  id?: string;\n  content: string;\n  score?: number;\n  bucket?: string;\n}\n\nexport interface QueryExplanation {\n  retrieved_memories?: RetrievedMemory[];\n  profile?: string | null;\n  graph_facts?: string[];\n}\n\nexport interface QueryUsage {\n  prompt_tokens?: number;\n  completion_tokens?: number;\n  total_tokens?: number;\n}\n\nexport interface QueryResult {\n  answer: string;\n  explanation?: QueryExplanation;\n  usage?: QueryUsage;\n}\n\nexport interface QueryOptions {\n  /**\n   * Buckets to fuse across. Defaults to `['default']`.\n   */\n  buckets?: string[];\n  /**\n   * Maximum number of memories to retrieve. Defaults to 8.\n   */\n  topK?: number;\n  /**\n   * If true, server skips the synthesis LLM call and returns retrieval-only.\n   * `answer` will be an empty string in that case. Defaults to false.\n   */\n  skipSynthesis?: boolean;\n  /**\n   * Whether to populate the `explanation` field. Defaults to true.\n   */\n  returnExplanation?: boolean;\n}\n\nexport interface ListMemoriesOptions {\n  limit?: number;\n  offset?: number;\n}\n\nexport interface ListMemoriesResult {\n  memories: Memory[];\n  total: number;\n  limit: number;\n  offset: number;\n}\n\nexport class EngramError extends Error {\n  override readonly name = 'EngramError';\n  readonly status: number;\n  readonly body: unknown;\n\n  constructor(message: string, status: number, body: unknown) {\n    super(message);\n    this.status = status;\n    this.body = body;\n  }\n}\n","import {\n  EngramError,\n  type Bucket,\n  type EngramClientOptions,\n  type ListMemoriesOptions,\n  type ListMemoriesResult,\n  type QueryOptions,\n  type QueryResult,\n  type StoreMemoryResult,\n} from './types.js';\n\nconst DEFAULT_BASE_URL = 'https://api.lumetra.io';\nconst DEFAULT_TIMEOUT_MS = 30_000;\n\nexport class EngramClient {\n  private readonly apiKey: string;\n  private readonly baseUrl: string;\n  private readonly fetchImpl: typeof fetch;\n  private readonly timeoutMs: number;\n\n  constructor(options: EngramClientOptions = {}) {\n    const apiKey =\n      options.apiKey ??\n      (typeof process !== 'undefined' ? process.env?.ENGRAM_API_KEY : undefined) ??\n      '';\n    if (!apiKey) {\n      throw new Error(\n        'EngramClient: apiKey is required. Pass it explicitly or set ENGRAM_API_KEY in your environment.',\n      );\n    }\n    const baseUrl =\n      options.baseUrl ??\n      (typeof process !== 'undefined' ? process.env?.ENGRAM_BASE_URL : undefined) ??\n      DEFAULT_BASE_URL;\n\n    this.apiKey = apiKey;\n    this.baseUrl = baseUrl.replace(/\\/+$/, '');\n    this.fetchImpl = options.fetch ?? globalThis.fetch;\n    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n\n    if (typeof this.fetchImpl !== 'function') {\n      throw new Error(\n        'EngramClient: no fetch implementation available. Use Node 18+, or pass options.fetch.',\n      );\n    }\n  }\n\n  private async request<T>(\n    path: string,\n    init: { method: string; body?: unknown; query?: Record<string, string | number | undefined> } = {\n      method: 'GET',\n    },\n  ): Promise<T> {\n    const url = new URL(`${this.baseUrl}${path}`);\n    if (init.query) {\n      for (const [k, v] of Object.entries(init.query)) {\n        if (v !== undefined) url.searchParams.set(k, String(v));\n      }\n    }\n\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), this.timeoutMs);\n\n    let res: Response;\n    try {\n      res = await this.fetchImpl(url.toString(), {\n        method: init.method,\n        headers: {\n          Authorization: `Bearer ${this.apiKey}`,\n          'Content-Type': 'application/json',\n        },\n        body: init.body !== undefined ? JSON.stringify(init.body) : undefined,\n        signal: controller.signal,\n      });\n    } finally {\n      clearTimeout(timer);\n    }\n\n    const text = await res.text();\n    let parsed: unknown = undefined;\n    if (text) {\n      try {\n        parsed = JSON.parse(text);\n      } catch {\n        parsed = text;\n      }\n    }\n\n    if (!res.ok) {\n      const detail =\n        parsed && typeof parsed === 'object' && parsed !== null && 'error' in parsed\n          ? (parsed as { error: unknown }).error\n          : parsed;\n      throw new EngramError(\n        `Engram API ${res.status}: ${typeof detail === 'string' ? detail : JSON.stringify(detail ?? '')}`,\n        res.status,\n        parsed,\n      );\n    }\n\n    return parsed as T;\n  }\n\n  // ---------- Memories ----------\n\n  async storeMemory(content: string, bucket: string = 'default'): Promise<StoreMemoryResult> {\n    return this.request<StoreMemoryResult>(\n      `/v1/buckets/${encodeURIComponent(bucket)}/memories`,\n      { method: 'POST', body: { content } },\n    );\n  }\n\n  async storeMemories(\n    contents: string[],\n    bucket: string = 'default',\n  ): Promise<{ memories: StoreMemoryResult[] }> {\n    return this.request<{ memories: StoreMemoryResult[] }>(\n      `/v1/buckets/${encodeURIComponent(bucket)}/memories`,\n      { method: 'POST', body: { memories: contents.map((content) => ({ content })) } },\n    );\n  }\n\n  async listMemories(\n    bucket: string = 'default',\n    options: ListMemoriesOptions = {},\n  ): Promise<ListMemoriesResult> {\n    return this.request<ListMemoriesResult>(\n      `/v1/buckets/${encodeURIComponent(bucket)}/memories`,\n      {\n        method: 'GET',\n        query: { limit: options.limit ?? 20, offset: options.offset ?? 0 },\n      },\n    );\n  }\n\n  async deleteMemory(memoryId: string, bucket: string = 'default'): Promise<void> {\n    await this.request<unknown>(\n      `/v1/buckets/${encodeURIComponent(bucket)}/memories/${encodeURIComponent(memoryId)}`,\n      { method: 'DELETE' },\n    );\n  }\n\n  async clearMemories(bucket: string): Promise<void> {\n    await this.request<unknown>(\n      `/v1/buckets/${encodeURIComponent(bucket)}/memories`,\n      { method: 'DELETE' },\n    );\n  }\n\n  // ---------- Query ----------\n\n  async query(question: string, options: QueryOptions = {}): Promise<QueryResult> {\n    const buckets = options.buckets ?? ['default'];\n    return this.request<QueryResult>('/v1/query', {\n      method: 'POST',\n      body: {\n        query: question,\n        buckets,\n        options: {\n          top_k: options.topK ?? 8,\n          return_explanation: options.returnExplanation ?? true,\n          skip_synthesis: options.skipSynthesis ?? false,\n        },\n      },\n    });\n  }\n\n  // ---------- Buckets ----------\n\n  async listBuckets(): Promise<Bucket[]> {\n    const result = await this.request<{ buckets: Bucket[] } | Bucket[]>(`/v1/buckets`, {\n      method: 'GET',\n    });\n    return Array.isArray(result) ? result : result.buckets;\n  }\n\n  async createBucket(name: string, description?: string): Promise<Bucket> {\n    return this.request<Bucket>('/v1/buckets', {\n      method: 'POST',\n      body: { name, description },\n    });\n  }\n\n  async deleteBucket(bucket: string): Promise<void> {\n    await this.request<unknown>(`/v1/buckets/${encodeURIComponent(bucket)}`, {\n      method: 'DELETE',\n    });\n  }\n\n  // ---------- Profile ----------\n\n  async getProfile(bucket: string = 'default'): Promise<{ profile: string | null }> {\n    return this.request<{ profile: string | null }>(\n      `/v1/buckets/${encodeURIComponent(bucket)}/profile`,\n      { method: 'GET' },\n    );\n  }\n\n  async regenerateProfile(bucket: string = 'default'): Promise<{ profile: string | null }> {\n    return this.request<{ profile: string | null }>(\n      `/v1/buckets/${encodeURIComponent(bucket)}/profile/regenerate`,\n      { method: 'POST' },\n    );\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@lumetra/engram",
+  "version": "0.1.0",
+  "description": "Official TypeScript client for Engram — durable, explainable memory for AI agents.",
+  "keywords": [
+    "engram",
+    "lumetra",
+    "memory",
+    "ai",
+    "agents",
+    "llm",
+    "mcp",
+    "rag"
+  ],
+  "license": "MIT",
+  "author": "Lumetra <hi@lumetra.io>",
+  "homepage": "https://lumetra.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lumetra-io/engram-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lumetra-io/engram-js/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run typecheck && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}