@rohankumar4179/engram-sdk 0.0.0-stage → 0.2.0

package/dist/llm.js

@@ -0,0 +1,188 @@
+export const DEFAULT_GEMINI_FALLBACKS = ["gemini-3.8-flash", "gemini-flash-lite-latest", "gemini-2.5-flash", "gemma-4-26b-a4b-it", "gemma-4-31b-it"];
+export class GeminiLLM {
+    name;
+    /** Model that answered the last request. */
+    lastModel;
+    keys;
+    current = 0;
+    /** "key|model" pairs that hit their daily quota. */
+    exhausted = new Set();
+    models;
+    temperature;
+    baseUrl;
+    fetchFn;
+    delay;
+    constructor(opts) {
+        this.keys = opts.apiKeys.map((k) => k.trim()).filter(Boolean);
+        if (this.keys.length === 0)
+            throw new Error("GeminiLLM needs at least one API key");
+        const main = opts.model ?? "gemini-flash-latest";
+        this.models = [main, ...(opts.fallbackModels ?? DEFAULT_GEMINI_FALLBACKS).filter((m) => m !== main)];
+        this.temperature = opts.temperature ?? 0.2;
+        this.baseUrl = opts.baseUrl ?? "https://generativelanguage.googleapis.com/v1beta";
+        this.fetchFn = opts.fetch ?? fetch;
+        this.delay = opts.retryDelayMs ?? 1000;
+        this.name = `gemini:${main}`;
+    }
+    async json(system, prompt, schema) {
+        const errors = [];
+        for (const model of this.models) {
+            const body = requestBody(model, system, prompt, schema, this.temperature);
+            // Each model gets two rounds over all keys before moving to the next model.
+            for (let attempt = 0; attempt < this.keys.length * 2; attempt++) {
+                const live = this.keys.filter((k) => !this.exhausted.has(`${k}|${model}`));
+                if (live.length === 0)
+                    break;
+                if (this.exhausted.has(`${this.keys[this.current]}|${model}`))
+                    this.current = this.keys.indexOf(live[0]);
+                const key = this.keys[this.current];
+                const r = await this.call(model, key, body);
+                if (r.ok) {
+                    this.lastModel = model;
+                    return r.value;
+                }
+                errors.push(`${model}: ${r.error}`);
+                if (r.fatal)
+                    throw new Error(`Gemini ${model}: ${r.error}`);
+                if (r.skipModel)
+                    break;
+                if (r.dailyLimit) {
+                    this.exhausted.add(`${key}|${model}`);
+                    continue;
+                }
+                if (r.rotate)
+                    this.current = (this.current + 1) % this.keys.length;
+                await sleep(this.delay * (attempt + 1));
+            }
+        }
+        throw new Error(`Gemini failed on all models — last error ${errors[errors.length - 1] ?? "unknown"}`);
+    }
+    async call(model, key, body) {
+        let res;
+        try {
+            res = await this.fetchFn(`${this.baseUrl}/models/${model}:generateContent`, {
+                method: "POST",
+                headers: { "content-type": "application/json", "x-goog-api-key": key },
+                body,
+                signal: AbortSignal.timeout(120_000),
+            });
+        }
+        catch (err) {
+            return { ok: false, error: `network: ${err.message}` };
+        }
+        const raw = await res.text();
+        const msg = () => {
+            try {
+                return JSON.parse(raw).error?.message?.slice(0, 160) ?? raw.slice(0, 160);
+            }
+            catch {
+                return raw.slice(0, 160);
+            }
+        };
+        // "PerDay" quota: this key is done with this model until tomorrow.
+        if (res.status === 429 && raw.includes("PerDay"))
+            return { ok: false, error: `HTTP 429 daily quota used up`, dailyLimit: true };
+        if (res.status === 429 || res.status === 403)
+            return { ok: false, error: `HTTP ${res.status} ${msg()}`, rotate: true };
+        if (res.status === 503 || res.status === 500 || res.status === 502 || res.status === 504)
+            return { ok: false, error: `HTTP ${res.status} ${msg()}`, rotate: true };
+        if (res.status === 404)
+            return { ok: false, error: `HTTP 404 ${msg()}`, skipModel: true };
+        if (!res.ok)
+            return { ok: false, error: `HTTP ${res.status} ${msg()}`, fatal: true };
+        const data = JSON.parse(raw);
+        const text = data.candidates?.[0]?.content?.parts?.map((p) => p.text ?? "").join("") ?? "";
+        if (!text)
+            return { ok: false, error: `empty response (${data.candidates?.[0]?.finishReason ?? data.promptFeedback?.blockReason ?? "unknown"})` };
+        const value = parseJsonLoose(text);
+        return value === undefined ? { ok: false, error: `invalid JSON: ${text.slice(0, 120)}` } : { ok: true, value };
+    }
+}
+/**
+ * Gemini models get native JSON mode with a schema. Gemma models (open
+ * weights, separate free quota) support neither system instructions nor
+ * schemas, so they get everything in one prompt and we parse the JSON out.
+ */
+function requestBody(model, system, prompt, schema, temperature) {
+    if (model.startsWith("gemma")) {
+        const text = `${system}\n\n${prompt}\n\nAnswer with ONLY a JSON object matching this JSON schema, no prose, no code fences:\n${JSON.stringify(schema)}`;
+        return JSON.stringify({ contents: [{ role: "user", parts: [{ text }] }], generationConfig: { temperature } });
+    }
+    return JSON.stringify({
+        systemInstruction: { parts: [{ text: system }] },
+        contents: [{ role: "user", parts: [{ text: prompt }] }],
+        generationConfig: { temperature, responseMimeType: "application/json", responseSchema: schema },
+    });
+}
+/** Parses JSON, also when wrapped in ```json fences or surrounded by text. */
+export function parseJsonLoose(text) {
+    const tryParse = (s) => {
+        try {
+            return JSON.parse(s);
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const direct = tryParse(text.trim());
+    if (direct !== undefined)
+        return direct;
+    const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(text);
+    if (fenced) {
+        const v = tryParse(fenced[1].trim());
+        if (v !== undefined)
+            return v;
+    }
+    const start = text.indexOf("{");
+    const end = text.lastIndexOf("}");
+    return start >= 0 && end > start ? tryParse(text.slice(start, end + 1)) : undefined;
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Returns scripted answers in order. For tests and offline demos. */
+export class ScriptedLLM {
+    answers;
+    name = "scripted";
+    calls = [];
+    constructor(answers) {
+        this.answers = answers;
+    }
+    async json(system, prompt) {
+        this.calls.push({ system, prompt });
+        if (this.answers.length === 0)
+            throw new Error("ScriptedLLM: no answers left");
+        return this.answers.shift();
+    }
+}
+/**
+ * Gemini embeddings (gemini-embedding-001) at 1536 dims, rotating keys on quota
+ * errors. Used for Walrus Memory manual mode.
+ */
+export function geminiEmbedder(apiKeys, opts = {}) {
+    const model = opts.model ?? "gemini-embedding-001";
+    const f = opts.fetch ?? fetch;
+    let next = 0;
+    return async (text) => {
+        let last = "";
+        for (let attempt = 0; attempt < apiKeys.length * 2; attempt++) {
+            const key = apiKeys[next % apiKeys.length];
+            const res = await f(`https://generativelanguage.googleapis.com/v1beta/models/${model}:embedContent`, {
+                method: "POST",
+                headers: { "content-type": "application/json", "x-goog-api-key": key },
+                body: JSON.stringify({ content: { parts: [{ text }] }, outputDimensionality: opts.dims ?? 1536 }),
+            });
+            if (res.ok) {
+                const j = (await res.json());
+                if (!j.embedding?.values?.length)
+                    throw new Error("Gemini embedding returned no values");
+                return j.embedding.values;
+            }
+            last = `HTTP ${res.status}`;
+            if (res.status !== 429 && res.status < 500)
+                throw new Error(`Gemini embedding failed: ${last} ${(await res.text()).slice(0, 200)}`);
+            next++;
+            await new Promise((r) => setTimeout(r, 500 * (attempt + 1)));
+        }
+        throw new Error(`Gemini embedding failed on every key: ${last}`);
+    };
+}
+//# sourceMappingURL=llm.js.map

package/dist/llm.js.map

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

package/dist/memwal-account.d.ts

@@ -0,0 +1,39 @@
+import type { SuiGrpcClient } from "@mysten/sui/grpc";
+/**
+ * A user's own Walrus Memory account, set up from the browser: the user's
+ * wallet creates the account and authorizes a delegate key that the Engram
+ * server holds for their agent. These helpers read that state from chain and
+ * build the two transactions; the wallet only signs.
+ */
+export interface MemwalIds {
+    packageId: string;
+    registryId: string;
+}
+export interface MemwalAccountInfo {
+    accountId: string;
+    owner: string;
+    delegates: {
+        publicKey: string;
+        suiAddress: string;
+        label: string;
+    }[];
+}
+/** A fresh Ed25519 delegate key; `secret` is the suiprivkey1… form. */
+export declare function newDelegateKey(): {
+    secret: string;
+    publicKey: string;
+    suiAddress: string;
+};
+export declare function delegateFromSecret(secret: string): {
+    publicKey: string;
+    suiAddress: string;
+};
+/** Finds the Walrus Memory account an address owns (each address can own one). */
+export declare function findMemwalAccount(client: SuiGrpcClient, owner: string, ids?: MemwalIds): Promise<string | null>;
+export declare function readMemwalAccount(client: SuiGrpcClient, accountId: string): Promise<MemwalAccountInfo>;
+/** Unsigned `create_account` transaction for `sender`, as base64 bytes ready for a wallet. */
+export declare function buildCreateAccountTx(client: SuiGrpcClient, sender: string, ids?: MemwalIds): Promise<string>;
+/** Unsigned `add_delegate_key` transaction (owner adds the server's key). */
+export declare function buildAddDelegateTx(client: SuiGrpcClient, sender: string, accountId: string, publicKeyHex: string, label: string, ids?: MemwalIds): Promise<string>;
+/** Submits wallet-signed bytes and waits for them to land. Returns the digest. */
+export declare function executeSigned(client: SuiGrpcClient, bytesBase64: string, signature: string): Promise<string>;

package/dist/memwal-account.js

@@ -0,0 +1,75 @@
+import { bcs } from "@mysten/sui/bcs";
+import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
+import { Transaction } from "@mysten/sui/transactions";
+import { normalizeSuiAddress } from "@mysten/sui/utils";
+import { MEMWAL_MAINNET } from "./remote.js";
+/** A fresh Ed25519 delegate key; `secret` is the suiprivkey1… form. */
+export function newDelegateKey() {
+    const kp = new Ed25519Keypair();
+    return { secret: kp.getSecretKey(), publicKey: Buffer.from(kp.getPublicKey().toRawBytes()).toString("hex"), suiAddress: kp.toSuiAddress() };
+}
+export function delegateFromSecret(secret) {
+    const kp = Ed25519Keypair.fromSecretKey(secret);
+    return { publicKey: Buffer.from(kp.getPublicKey().toRawBytes()).toString("hex"), suiAddress: kp.toSuiAddress() };
+}
+/** Finds the Walrus Memory account an address owns (each address can own one). */
+export async function findMemwalAccount(client, owner, ids = MEMWAL_MAINNET) {
+    const { object } = await client.getObject({ objectId: ids.registryId, include: { json: true } });
+    const tableId = object.json?.accounts?.id;
+    if (!tableId)
+        throw new Error("Walrus Memory registry has no accounts table");
+    try {
+        const f = await client.getDynamicField({ parentId: tableId, name: { type: "address", bcs: bcs.Address.serialize(normalizeSuiAddress(owner)).toBytes() } });
+        const value = f.dynamicField?.value;
+        if (!value)
+            return null;
+        // Table<address, ID>: the value is the 32-byte account ID.
+        return normalizeSuiAddress(Buffer.from(value.bcs).toString("hex"));
+    }
+    catch (err) {
+        if (/not ?found|does not exist/i.test(String(err.message)))
+            return null;
+        throw err;
+    }
+}
+export async function readMemwalAccount(client, accountId) {
+    const { object } = await client.getObject({ objectId: accountId, include: { json: true } });
+    const j = object.json;
+    if (!j?.owner)
+        throw new Error(`${accountId} is not a Walrus Memory account`);
+    return {
+        accountId,
+        owner: normalizeSuiAddress(j.owner),
+        delegates: (j.delegate_keys ?? []).map((d) => ({
+            publicKey: /^[0-9a-f]+$/i.test(d.public_key) ? d.public_key.toLowerCase() : Buffer.from(d.public_key, "base64").toString("hex"),
+            suiAddress: normalizeSuiAddress(d.sui_address),
+            label: d.label ?? "",
+        })),
+    };
+}
+/** Unsigned `create_account` transaction for `sender`, as base64 bytes ready for a wallet. */
+export async function buildCreateAccountTx(client, sender, ids = MEMWAL_MAINNET) {
+    const tx = new Transaction();
+    tx.setSender(sender);
+    tx.moveCall({ target: `${ids.packageId}::account::create_account`, arguments: [tx.object(ids.registryId), tx.object.clock()] });
+    return Buffer.from(await tx.build({ client })).toString("base64");
+}
+/** Unsigned `add_delegate_key` transaction (owner adds the server's key). */
+export async function buildAddDelegateTx(client, sender, accountId, publicKeyHex, label, ids = MEMWAL_MAINNET) {
+    const tx = new Transaction();
+    tx.setSender(sender);
+    tx.moveCall({
+        target: `${ids.packageId}::account::add_delegate_key`,
+        arguments: [tx.object(accountId), tx.object(ids.registryId), tx.pure.vector("u8", Buffer.from(publicKeyHex, "hex")), tx.pure.string(label), tx.object.clock()],
+    });
+    return Buffer.from(await tx.build({ client })).toString("base64");
+}
+/** Submits wallet-signed bytes and waits for them to land. Returns the digest. */
+export async function executeSigned(client, bytesBase64, signature) {
+    const res = await client.executeTransaction({ transaction: Buffer.from(bytesBase64, "base64"), signatures: [signature] });
+    if (res.$kind !== "Transaction")
+        throw new Error(`transaction failed: ${JSON.stringify(res.FailedTransaction?.status)}`);
+    await client.waitForTransaction({ digest: res.Transaction.digest });
+    return res.Transaction.digest;
+}
+//# sourceMappingURL=memwal-account.js.map

package/dist/memwal-account.js.map

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

package/dist/merkle.d.ts

@@ -0,0 +1,14 @@
+import type { MerkleProofStep } from "./types.js";
+/** Root of an empty tree. */
+export declare const EMPTY_ROOT: string;
+/**
+ * Binary Merkle tree over hex leaf values, in the given order.
+ * An odd node at the end of a level is carried up unchanged.
+ */
+export declare class MerkleTree {
+    private levels;
+    constructor(leaves: string[]);
+    get root(): string;
+    proof(index: number): MerkleProofStep[];
+}
+export declare function verifyProof(leafHex: string, proof: MerkleProofStep[], rootHex: string): boolean;

package/dist/merkle.js

@@ -0,0 +1,69 @@
+import { bytesToHex, hexToBytes, sha256Bytes } from "./crypto.js";
+// Domain separation so a leaf can never be passed off as an inner node.
+const LEAF = 0x00;
+const NODE = 0x01;
+function hashLeaf(leafHex) {
+    return bytesToHex(sha256Bytes(concat([LEAF], hexToBytes(leafHex))));
+}
+function hashNode(leftHex, rightHex) {
+    return bytesToHex(sha256Bytes(concat([NODE], hexToBytes(leftHex), hexToBytes(rightHex))));
+}
+function concat(prefix, ...parts) {
+    const out = new Uint8Array(prefix.length + parts.reduce((n, p) => n + p.length, 0));
+    out.set(prefix, 0);
+    let o = prefix.length;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+}
+/** Root of an empty tree. */
+export const EMPTY_ROOT = bytesToHex(sha256Bytes(new Uint8Array([NODE])));
+/**
+ * Binary Merkle tree over hex leaf values, in the given order.
+ * An odd node at the end of a level is carried up unchanged.
+ */
+export class MerkleTree {
+    levels;
+    constructor(leaves) {
+        let level = leaves.map(hashLeaf);
+        this.levels = [level];
+        while (level.length > 1) {
+            const next = [];
+            for (let i = 0; i < level.length; i += 2) {
+                const l = level[i];
+                const r = level[i + 1];
+                next.push(r === undefined ? l : hashNode(l, r));
+            }
+            this.levels.push(next);
+            level = next;
+        }
+    }
+    get root() {
+        const top = this.levels[this.levels.length - 1];
+        return top[0] ?? EMPTY_ROOT;
+    }
+    proof(index) {
+        if (index < 0 || index >= this.levels[0].length)
+            throw new Error(`leaf ${index} out of range`);
+        const steps = [];
+        let i = index;
+        for (let d = 0; d < this.levels.length - 1; d++) {
+            const level = this.levels[d];
+            const isRight = i % 2 === 1;
+            const sib = isRight ? level[i - 1] : level[i + 1];
+            if (sib !== undefined)
+                steps.push({ hash: sib, left: isRight });
+            i = Math.floor(i / 2);
+        }
+        return steps;
+    }
+}
+export function verifyProof(leafHex, proof, rootHex) {
+    let h = hashLeaf(leafHex);
+    for (const s of proof)
+        h = s.left ? hashNode(s.hash, h) : hashNode(h, s.hash);
+    return h === rootHex;
+}
+//# sourceMappingURL=merkle.js.map

package/dist/merkle.js.map

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

package/dist/mind.d.ts

@@ -0,0 +1,150 @@
+import { type Anchorer, type SuiNetwork } from "./anchor.js";
+import { Engram, type ForgetResult, type ObserveInput, type SleepReport, type VerifyReport } from "./engram.js";
+import { type LLM } from "./llm.js";
+import { type RemoteMemory } from "./remote.js";
+import { type LinkInfo, type LinkStart, type SyncResult } from "./link.js";
+import type { Belief, Commit, Episode, Receipt } from "./types.js";
+/**
+ * Settings for `engram()`. Anything left out is read from the environment
+ * (`.env`: MEMWAL_KEY, MEMWAL_ACCOUNT_ID, TATUM_API_KEY, GEMINI_API_KEYS, …).
+ */
+export interface EngramConfig {
+    /** Agent name — lowercase letters, digits and dashes. Used for a new repo. */
+    agent: string;
+    /** Folder for `.engram/` (default: the current directory). */
+    dir?: string;
+    /** Walrus Memory account, a ready remote, or "memory" for an in-process store (tests). */
+    walrus?: {
+        accountId: string;
+        key: string;
+        serverUrl?: string;
+    } | RemoteMemory | "memory";
+    /** Tatum Sui gateway (mainnet) — wallet reads and anchor checks. */
+    tatum?: {
+        apiKey: string;
+    };
+    /** LLM for `sleep()`: Gemini keys, or any `LLM`. */
+    llm?: {
+        gemini: string[];
+        model?: string;
+    } | LLM;
+    /** Anchor commits with the engram_anchor Move module. */
+    anchor?: {
+        packageId: string;
+        mnemonic: string;
+        network?: SuiNetwork;
+    } | Anchorer | false;
+    /** Domain hint for consolidation, e.g. "a wallet-watching agent". */
+    context?: string;
+    /** Where unspecified settings come from (default: process.env). */
+    env?: Record<string, string | undefined>;
+}
+export interface WrapOptions<In, Out> {
+    /** What to look up beliefs about (default: the input as JSON). */
+    query?: (input: In) => string;
+    /** One-line description of the decision for the receipt (default: the output as JSON). */
+    action?: (output: Out, input: In) => string;
+    /** Beliefs the decision used: ids like "b_rent" (default: every belief the agent was given). */
+    used?: (output: Out, beliefs: Belief[]) => string[];
+    /** Also record the input as an episode (default true). */
+    observe?: boolean | ((input: In) => ObserveInput);
+    /** Max beliefs handed to the agent (default 6). */
+    limit?: number;
+}
+/** A wrapped agent: same call, plus the last receipt. */
+export interface WrappedAgent<In, Out> {
+    (input: In): Promise<Out>;
+    /** Receipt of the most recent call (null before the first commit). */
+    lastReceipt: Receipt | null;
+}
+/**
+ * The high-level API: one object for an agent's memory.
+ *
+ * ```ts
+ * const mind = engram({ agent: "money-ops" });
+ * const agent = mind.wrap(myAgent);         // beliefs in, signed receipts out
+ * mind.observe({ source: "tatum", data: tx });
+ * await mind.sleep();                       // episodes → beliefs
+ * await mind.commit("weekly");              // Merkle root → Walrus → Sui
+ * await mind.beliefs({ about: "rent" });
+ * mind.at("2026-10-25");                    // time travel
+ * mind.forget("ep_…");                      // provable forgetting
+ * await mind.verify("r_…");                 // proof check
+ * ```
+ */
+export declare class Mind {
+    private llmFactory;
+    private context?;
+    readonly core: Engram;
+    private llmInstance?;
+    constructor(core: Engram, llmFactory: () => LLM, context?: string | undefined);
+    get agent(): string;
+    /** Records an episode (encrypted with its own key). */
+    observe(input: ObserveInput): Episode;
+    /** Consolidates new episodes into beliefs with the configured LLM. */
+    sleep(opts?: {
+        context?: string;
+        batchSize?: number;
+    }): Promise<SleepReport>;
+    /**
+     * Signs and stores a snapshot of the current beliefs, anchored on Sui. If the
+     * agent is linked to a dashboard, the new history is synced too (a failed
+     * sync never fails the commit; see `lastSyncError`).
+     */
+    commit(message: string): Promise<Commit>;
+    /** Why the last automatic sync after commit failed, if it did. */
+    lastSyncError: string | null;
+    /**
+     * Links this agent to an Engram web app account (a Sui wallet). `onCode`
+     * gets the code and URL to show the owner; resolves once they approve.
+     */
+    link(opts: {
+        server?: string;
+        label?: string;
+        onCode: (start: LinkStart) => void;
+    }): Promise<LinkInfo>;
+    /** Uploads the audit bundle to the linked dashboard (verified there before it's shown). */
+    sync(): Promise<SyncResult>;
+    get linked(): LinkInfo | null;
+    unlink(): boolean;
+    /**
+     * Current beliefs. With `about`, the most relevant ones (Walrus Memory
+     * semantic recall, keyword fallback offline).
+     */
+    beliefs(opts?: {
+        about?: string;
+        limit?: number;
+    }): Promise<Belief[]>;
+    /** Beliefs as they were at a commit, `HEAD~n`, or a date ("2026-10-25"). */
+    at(ref: string): Belief[];
+    /** Destroys an episode's key; dependent beliefs are retracted or revised. */
+    forget(episodeId: string, reason?: string): ForgetResult;
+    /** Verifies a receipt (`r_…`) or a commit (id, `HEAD`, date) end to end. */
+    verify(ref: string, opts?: {
+        offline?: boolean;
+    }): Promise<VerifyReport>;
+    log(): Commit[];
+    diff(from: string, to?: string): import("./engram.js").BeliefDiff;
+    blame(belief: string): {
+        belief: Belief;
+        history: Belief[];
+        evidence: import("./engram.js").BlameEntry[];
+    };
+    receipts(): Receipt[];
+    /**
+     * Wraps an existing agent function. Each call: the relevant committed
+     * beliefs are passed in, the agent runs, and a signed receipt records what it
+     * decided and which beliefs it relied on.
+     *
+     * ```ts
+     * const agent = mind.wrap(async (tx, beliefs) => decide(tx, beliefs), {
+     *   used: (out) => out.beliefIds,
+     * });
+     * const decision = await agent(tx);
+     * agent.lastReceipt; // r_…
+     * ```
+     */
+    wrap<In, Out>(fn: (input: In, beliefs: Belief[]) => Promise<Out> | Out, opts?: WrapOptions<In, Out>): WrappedAgent<In, Out>;
+}
+/** Opens (or creates) an agent's memory. See {@link EngramConfig}. */
+export declare function engram(cfg: EngramConfig): Mind;