@rohankumar4179/engram-sdk 0.0.0-stage → 0.1.0

package/dist/remote.d.ts

@@ -0,0 +1,112 @@
+export interface RemoteHit {
+    blobId: string;
+    text: string;
+    distance: number;
+}
+/**
+ * Durable remote for Engram objects. The real one is Walrus Memory;
+ * tests use the in-memory one.
+ */
+export interface RemoteMemory {
+    /** Stores each text and returns its Walrus blob ID, in order. */
+    putMany(items: {
+        namespace: string;
+        text: string;
+    }[]): Promise<string[]>;
+    /**
+     * `deep`: also look where cheap search can't (e.g. Walrus Memory manual-mode
+     * records) — for verification, which needs one exact record.
+     */
+    search(namespace: string, query: string, limit?: number, opts?: SearchOptions): Promise<RemoteHit[]>;
+}
+export interface SearchOptions {
+    deep?: boolean;
+}
+export interface WalrusMemoryConfig {
+    key: string;
+    accountId: string;
+    serverUrl?: string;
+    /**
+     * Manual-mode fallback: when the relayer's own embedding service fails, Engram
+     * embeds locally, Seal-encrypts with the account owner's key and has the relayer
+     * only store the ciphertext + vector. Reads use the same path.
+     */
+    manual?: ManualModeConfig;
+}
+export interface ManualModeConfig {
+    /** Account owner's Sui private key (suiprivkey1…) — Seal encrypt/decrypt. */
+    suiPrivateKey: string;
+    /** Text → embedding vector (1536 dims, like the relayer's own). */
+    embed: (text: string) => Promise<number[]>;
+    /** Walrus Memory Move package and AccountRegistry (mainnet defaults). */
+    packageId?: string;
+    registryId?: string;
+    /** Sui client for Seal and Walrus reads (a gRPC client works). */
+    suiClient: unknown;
+}
+/** Walrus Memory on Sui Mainnet (read from the account object and its creating transaction). */
+export declare const MEMWAL_MAINNET: {
+    packageId: string;
+    registryId: string;
+};
+export declare class WalrusMemoryRemote implements RemoteMemory {
+    private cfg;
+    private client;
+    private manualClient?;
+    /** Until when writes go straight to manual mode after a relayer failure. */
+    private manualUntil;
+    /** Set when the last write used the manual fallback (for logs and the UI). */
+    lastWriteMode: "relayer" | "manual";
+    constructor(cfg: WalrusMemoryConfig);
+    private manual;
+    putMany(items: {
+        namespace: string;
+        text: string;
+    }[]): Promise<string[]>;
+    private putManual;
+    private putRelayer;
+    /**
+     * Relayer recall first. Manual-mode recall (embed locally, decrypt here) runs
+     * when the relayer fails, or for a deep search — it is slower and only sees
+     * records written in manual mode. Results are merged by blob ID.
+     */
+    search(namespace: string, query: string, limit?: number, opts?: SearchOptions): Promise<RemoteHit[]>;
+    health(): Promise<boolean>;
+}
+/** Offline stand-in. Blob IDs are sha256 of the text, base64url. */
+export declare class InMemoryRemote implements RemoteMemory {
+    readonly items: {
+        namespace: string;
+        text: string;
+        blobId: string;
+    }[];
+    putMany(items: {
+        namespace: string;
+        text: string;
+    }[]): Promise<string[]>;
+    search(namespace: string, query: string, limit?: number): Promise<RemoteHit[]>;
+}
+/**
+ * Writes go to `primary`; searches merge `primary` and `secondary`. Used when an
+ * agent moves to its owner's own Walrus Memory account: older memories stay
+ * readable (and verifiable) in the account they were written to.
+ */
+export declare class CombinedRemote implements RemoteMemory {
+    readonly primary: RemoteMemory;
+    readonly secondary: RemoteMemory;
+    constructor(primary: RemoteMemory, secondary: RemoteMemory);
+    putMany(items: {
+        namespace: string;
+        text: string;
+    }[]): Promise<string[]>;
+    search(namespace: string, query: string, limit?: number, opts?: SearchOptions): Promise<RemoteHit[]>;
+}
+/**
+ * The relayer limits each key to 60 weighted requests a minute and answers 429
+ * with retry_after_seconds; it also has brief 5xx hiccups. Wait and retry
+ * instead of failing.
+ */
+export declare function relayerRetry<T>(fn: () => Promise<T>, opts?: {
+    attempts?: number;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<T>;

package/dist/remote.js

@@ -0,0 +1,232 @@
+import { MemWal } from "@mysten-incubation/memwal";
+import { MemWalManual } from "@mysten-incubation/memwal/manual";
+import { sha256Bytes } from "./crypto.js";
+/** Walrus Memory on Sui Mainnet (read from the account object and its creating transaction). */
+export const MEMWAL_MAINNET = {
+    packageId: "0xe7c16fbea0560e7057e2bf7422feaa4fb313749fc69c9e9092fac7a33b81d7f5",
+    registryId: "0x8bf82c9e09e36b8d1c38298f68b7cb68e7b8762887e7592add9986d5e9cf199f",
+};
+/** Errors that mean the relayer's server-side pipeline is down (not our request). */
+const RELAYER_DOWN = /embedding|internal error|internal server error|\b5\d\d\b|unavailable|timed? ?out/i;
+export class WalrusMemoryRemote {
+    cfg;
+    client;
+    manualClient;
+    /** Until when writes go straight to manual mode after a relayer failure. */
+    manualUntil = 0;
+    /** Set when the last write used the manual fallback (for logs and the UI). */
+    lastWriteMode = "relayer";
+    constructor(cfg) {
+        this.cfg = cfg;
+        this.client = MemWal.create({
+            key: cfg.key,
+            accountId: cfg.accountId,
+            serverUrl: cfg.serverUrl ?? "https://relayer.memory.walrus.xyz",
+            requestTimeoutMs: 60_000,
+        });
+    }
+    manual() {
+        const m = this.cfg.manual;
+        if (!m)
+            return undefined;
+        if (!this.manualClient) {
+            this.manualClient = MemWalManual.create({
+                key: this.cfg.key,
+                accountId: this.cfg.accountId,
+                serverUrl: this.cfg.serverUrl ?? "https://relayer.memory.walrus.xyz",
+                suiPrivateKey: m.suiPrivateKey,
+                suiClient: m.suiClient,
+                embeddingApiKey: "local", // embedding is done by m.embed below
+                packageId: m.packageId ?? MEMWAL_MAINNET.packageId,
+                registryId: m.registryId ?? MEMWAL_MAINNET.registryId,
+            });
+            // The SDK only knows OpenAI-style embedding APIs; use ours instead.
+            this.manualClient.embed = m.embed;
+        }
+        return this.manualClient;
+    }
+    async putMany(items) {
+        if (items.length === 0)
+            return [];
+        const manual = this.manual();
+        if (manual && Date.now() < this.manualUntil)
+            return this.putManual(manual, items);
+        try {
+            const ids = await this.putRelayer(items);
+            this.lastWriteMode = "relayer";
+            return ids;
+        }
+        catch (err) {
+            if (!manual || !RELAYER_DOWN.test(err.message))
+                throw err;
+            this.manualUntil = Date.now() + 10 * 60_000;
+            return this.putManual(manual, items);
+        }
+    }
+    async putManual(manual, items) {
+        const out = [];
+        // Three at a time keeps Seal key servers and the embedder within rate limits.
+        for (let i = 0; i < items.length; i += 3) {
+            const batch = items.slice(i, i + 3);
+            const res = await Promise.all(batch.map((it) => relayerRetry(() => manual.rememberManual(it.text, it.namespace))));
+            for (const r of res) {
+                if (!r.blob_id)
+                    throw new Error("Walrus Memory manual write returned no blob ID");
+                out.push(r.blob_id);
+            }
+        }
+        this.lastWriteMode = "manual";
+        return out;
+    }
+    async putRelayer(items) {
+        const out = [];
+        // Keep batches small so one slow item doesn't hold up everything.
+        for (let i = 0; i < items.length; i += 20) {
+            const batch = items.slice(i, i + 20);
+            const res = await relayerRetry(() => this.client.rememberBulkAndWait(batch, { timeoutMs: 300_000 }));
+            batch.forEach((_, j) => {
+                const r = res.results[j];
+                if (!r || r.status !== "done" || !r.blob_id) {
+                    throw new Error(`Walrus Memory write failed: ${r?.error ?? r?.status ?? "no result"}`);
+                }
+                out.push(r.blob_id);
+            });
+        }
+        return out;
+    }
+    /**
+     * Relayer recall first. Manual-mode recall (embed locally, decrypt here) runs
+     * when the relayer fails, or for a deep search — it is slower and only sees
+     * records written in manual mode. Results are merged by blob ID.
+     */
+    async search(namespace, query, limit = 10, opts = {}) {
+        const manual = this.manual();
+        let auto = [];
+        let autoErr = null;
+        try {
+            const res = await relayerRetry(() => this.client.recall({ query, limit, namespace }));
+            auto = res.results.map((r) => ({ blobId: r.blob_id, text: r.text, distance: r.distance }));
+        }
+        catch (err) {
+            autoErr = err;
+        }
+        if (!manual || (!autoErr && !opts.deep)) {
+            if (autoErr)
+                throw autoErr;
+            return auto;
+        }
+        let man = [];
+        try {
+            man = await quietSealLogs(() => manual.recallManual(query, { limit, namespace })).then((res) => res.results.flatMap((r) => ("text" in r ? [{ blobId: r.blob_id, text: r.text, distance: r.distance }] : [])));
+        }
+        catch (err) {
+            if (autoErr)
+                throw autoErr;
+        }
+        const merged = new Map();
+        for (const r of [...auto, ...man]) {
+            const prev = merged.get(r.blobId);
+            if (!prev || r.distance < prev.distance)
+                merged.set(r.blobId, r);
+        }
+        return [...merged.values()].sort((x, y) => x.distance - y.distance).slice(0, limit);
+    }
+    async health() {
+        return (await this.client.health()).status === "ok";
+    }
+}
+/** Offline stand-in. Blob IDs are sha256 of the text, base64url. */
+export class InMemoryRemote {
+    items = [];
+    async putMany(items) {
+        return items.map((it) => {
+            const blobId = Buffer.from(sha256Bytes(Buffer.from(it.namespace + "\n" + it.text))).toString("base64url");
+            this.items.push({ ...it, blobId });
+            return blobId;
+        });
+    }
+    async search(namespace, query, limit = 10) {
+        const words = query.toLowerCase().split(/\W+/).filter(Boolean);
+        return this.items
+            .filter((i) => i.namespace === namespace)
+            .map((i) => {
+            const t = i.text.toLowerCase();
+            const hits = words.filter((w) => t.includes(w)).length;
+            return { blobId: i.blobId, text: i.text, distance: words.length ? 1 - hits / words.length : 1 };
+        })
+            .sort((a, b) => a.distance - b.distance)
+            .slice(0, limit);
+    }
+}
+/**
+ * Writes go to `primary`; searches merge `primary` and `secondary`. Used when an
+ * agent moves to its owner's own Walrus Memory account: older memories stay
+ * readable (and verifiable) in the account they were written to.
+ */
+export class CombinedRemote {
+    primary;
+    secondary;
+    constructor(primary, secondary) {
+        this.primary = primary;
+        this.secondary = secondary;
+    }
+    putMany(items) {
+        return this.primary.putMany(items);
+    }
+    async search(namespace, query, limit = 10, opts) {
+        const [a, b] = await Promise.allSettled([this.primary.search(namespace, query, limit, opts), this.secondary.search(namespace, query, limit, opts)]);
+        if (a.status === "rejected" && b.status === "rejected")
+            throw a.reason;
+        const merged = new Map();
+        for (const h of [...(a.status === "fulfilled" ? a.value : []), ...(b.status === "fulfilled" ? b.value : [])]) {
+            const prev = merged.get(h.blobId);
+            if (!prev || h.distance < prev.distance)
+                merged.set(h.blobId, h);
+        }
+        return [...merged.values()].sort((x, y) => x.distance - y.distance).slice(0, limit);
+    }
+}
+/**
+ * Manual recall tries to decrypt every hit in the namespace, including records
+ * written by the relayer under a different Seal identity; the SDK logs each of
+ * those expected failures. Keep them out of the agent's output.
+ */
+async function quietSealLogs(fn) {
+    const orig = console.error;
+    console.error = (...args) => {
+        if (typeof args[0] === "string" && args[0].startsWith("[MemWalManual]"))
+            return;
+        orig(...args);
+    };
+    try {
+        return await fn();
+    }
+    finally {
+        console.error = orig;
+    }
+}
+/**
+ * The relayer limits each key to 60 weighted requests a minute and answers 429
+ * with retry_after_seconds; it also has brief 5xx hiccups. Wait and retry
+ * instead of failing.
+ */
+export async function relayerRetry(fn, opts = {}) {
+    const attempts = opts.attempts ?? 4;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    for (let i = 0;; i++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            const msg = String(err.message ?? err);
+            const limited = /\b429\b|rate limit/i.test(msg);
+            // Transient server errors (the relayer has been flaky) get a short backoff too.
+            const transient = /\b50[0234]\b|internal server error|ECONNRESET|fetch failed/i.test(msg);
+            if (i + 1 >= attempts || (!limited && !transient))
+                throw err;
+            const after = limited ? Number(/retry_after_seconds"?\s*:\s*(\d+)/.exec(msg)?.[1] ?? 30) : 5 * (i + 1);
+            await sleep(Math.min(after, 90) * 1000 + 500);
+        }
+    }
+}
+//# sourceMappingURL=remote.js.map

package/dist/remote.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote.js","sourceRoot":"","sources":["../src/remote.ts"],"names":[],"mappings":"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"}

package/dist/store.d.ts

@@ -0,0 +1,28 @@
+/** A JSON file written atomically (temp file + rename). */
+export declare class JsonFile<T> {
+    readonly path: string;
+    constructor(path: string);
+    read(): T | null;
+    write(value: T): void;
+}
+/**
+ * The `.engram/` folder — Engram's local copy of the agent's mind, like `.git/`.
+ *
+ *   config.json          agent name, public key, namespaces
+ *   agent.key            Ed25519 signing key (secret)
+ *   master.key           wraps the data keys (secret)
+ *   vault.json           wrapped per-episode data keys
+ *   HEAD                 current commit ID
+ *   objects/<kind>/<id>.json
+ */
+export declare class LocalStore {
+    readonly root: string;
+    constructor(root: string);
+    file<T>(...parts: string[]): JsonFile<T>;
+    exists(): boolean;
+    readText(name: string): string | null;
+    writeText(name: string, value: string): void;
+    put<T>(kind: string, id: string, value: T): void;
+    get<T>(kind: string, id: string): T | null;
+    list<T>(kind: string): T[];
+}

package/dist/store.js

@@ -0,0 +1,72 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** A JSON file written atomically (temp file + rename). */
+export class JsonFile {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    read() {
+        if (!existsSync(this.path))
+            return null;
+        return JSON.parse(readFileSync(this.path, "utf8"));
+    }
+    write(value) {
+        mkdirSync(dirname(this.path), { recursive: true });
+        const tmp = `${this.path}.${process.pid}.tmp`;
+        writeFileSync(tmp, JSON.stringify(value, null, 2) + "\n", { mode: 0o600 });
+        renameSync(tmp, this.path);
+    }
+}
+/**
+ * The `.engram/` folder — Engram's local copy of the agent's mind, like `.git/`.
+ *
+ *   config.json          agent name, public key, namespaces
+ *   agent.key            Ed25519 signing key (secret)
+ *   master.key           wraps the data keys (secret)
+ *   vault.json           wrapped per-episode data keys
+ *   HEAD                 current commit ID
+ *   objects/<kind>/<id>.json
+ */
+export class LocalStore {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    file(...parts) {
+        return new JsonFile(join(this.root, ...parts));
+    }
+    exists() {
+        return existsSync(join(this.root, "config.json"));
+    }
+    readText(name) {
+        const p = join(this.root, name);
+        return existsSync(p) ? readFileSync(p, "utf8").trim() : null;
+    }
+    writeText(name, value) {
+        mkdirSync(this.root, { recursive: true });
+        writeFileSync(join(this.root, name), value + "\n", { mode: 0o600 });
+    }
+    put(kind, id, value) {
+        this.file("objects", kind, `${safe(id)}.json`).write(value);
+    }
+    get(kind, id) {
+        return this.file("objects", kind, `${safe(id)}.json`).read();
+    }
+    list(kind) {
+        const dir = join(this.root, "objects", kind);
+        if (!existsSync(dir))
+            return [];
+        return readdirSync(dir)
+            .filter((f) => f.endsWith(".json"))
+            .sort()
+            .map((f) => JSON.parse(readFileSync(join(dir, f), "utf8")));
+    }
+}
+/** Belief keys look like "b_rent@2"; '@' is fine on all platforms but be strict anyway. */
+function safe(id) {
+    if (!/^[A-Za-z0-9_@.-]+$/.test(id))
+        throw new Error(`invalid object id: ${id}`);
+    return id;
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}

package/dist/tatum.d.ts

@@ -0,0 +1,83 @@
+import { SuiGrpcClient } from "@mysten/sui/grpc";
+/** Walrus `Blob` Move type on Sui Mainnet. */
+export declare const WALRUS_BLOB_TYPE_MAINNET = "0xfdc88f7d7cf30afab2f82e8380d11ee8f70efb90e863d1de8616fae1bb09ea77::blob::Blob";
+/** Tatum's Sui Mainnet gRPC gateway (Sui JSON-RPC was switched off in July 2026). */
+export declare const TATUM_SUI_GRPC_HOST = "sui-mainnet-grpc.gateway.tatum.io:443";
+export interface TatumOptions {
+    apiKey: string;
+    network?: "mainnet";
+    /** Override the gRPC host (`host:port`). */
+    host?: string;
+    /** Use a ready-made client instead (tests). */
+    client?: SuiGrpcClient;
+}
+export interface SuiBlobObject {
+    objectId: string;
+    blobId: string;
+    size: number;
+    registeredEpoch: number;
+    certifiedEpoch: number | null;
+    previousTransaction: string;
+}
+export interface SuiTx {
+    digest: string;
+    checkpoint: string;
+    timestampMs: number;
+}
+/** Walrus stores blob_id as a u256; the SDK shows it as little-endian base64url. */
+export declare function blobIdFromU256(u256: string): string;
+/**
+ * Sui Mainnet through Tatum's gRPC gateway. All of Engram's mainnet reads (and
+ * mainnet anchor transactions) go through here.
+ */
+export declare class TatumSui {
+    readonly host: string;
+    private apiKey;
+    private _client?;
+    constructor(opts: TatumOptions);
+    /** The Sui SDK client, connected to Tatum with native gRPC (Tatum doesn't serve gRPC-Web). */
+    get client(): SuiGrpcClient;
+    /** Retries Tatum's transient failures (rate limit, unavailable upstream). */
+    private retry;
+    latestCheckpoint(): Promise<string>;
+    getObject(id: string): Promise<SuiObjectData | null>;
+    /** Owner address of a Walrus Memory account (the wallet that owns the blobs). */
+    memwalAccountOwner(accountId: string): Promise<string>;
+    /** All Walrus Blob objects owned by an address. */
+    ownedBlobs(owner: string, blobType?: string): AsyncGenerator<SuiBlobObject>;
+    getTransaction(digest: string): Promise<SuiTx>;
+    /** Recent transactions that touched an address (sent or received), newest first. */
+    transactionsOf(address: string, limit?: number): Promise<SuiTxDetail[]>;
+    /** Decimals and symbol of a coin type, or null if it has no metadata. */
+    coinMetadata(coinType: string): Promise<{
+        decimals: number;
+        symbol: string;
+    } | null>;
+}
+export interface SuiObjectData {
+    objectId: string;
+    version: string;
+    type?: string;
+    owner?: unknown;
+    previousTransaction?: string;
+    content?: {
+        fields?: unknown;
+    };
+}
+export interface SuiTxDetail {
+    digest: string;
+    timestampMs?: string;
+    checkpoint?: string;
+    transaction?: {
+        data?: {
+            sender?: string;
+        };
+    };
+    balanceChanges?: {
+        owner: {
+            AddressOwner?: string;
+        } | unknown;
+        coinType: string;
+        amount: string;
+    }[];
+}