@rohankumar4179/engram-sdk 0.0.0-stage → 0.2.0

package/dist/consolidator.d.ts

@@ -0,0 +1,62 @@
+import type { LLM } from "./llm.js";
+import type { Belief, EpisodeContent } from "./types.js";
+/** One change the consolidator wants to make to the belief set. */
+export type BeliefOp = {
+    op: "create";
+    key: string;
+    statement: string;
+    confidence: number;
+    evidence: string[];
+    tags: string[];
+    reason: string;
+} | {
+    op: "revise";
+    belief: string;
+    statement: string;
+    confidence: number;
+    evidence: string[];
+    tags?: string[];
+    reason: string;
+} | {
+    op: "retract";
+    belief: string;
+    reason: string;
+};
+export interface ConsolidationInput {
+    episodes: {
+        id: string;
+        content: EpisodeContent;
+        summary?: string;
+    }[];
+    beliefs: Belief[];
+    /** Optional domain hint, e.g. "You manage a crypto wallet for one owner." */
+    context?: string;
+}
+interface RawOp {
+    op?: string;
+    key?: string;
+    belief?: string;
+    statement?: string;
+    confidence?: number;
+    evidence?: string[];
+    tags?: string[];
+    reason?: string;
+}
+export declare function buildPrompt(input: ConsolidationInput): string;
+/** Asks the LLM for belief changes and drops anything malformed or ungrounded. */
+export declare function proposeOps(llm: LLM, input: ConsolidationInput): Promise<{
+    ops: BeliefOp[];
+    rejected: {
+        op: unknown;
+        why: string;
+    }[];
+}>;
+export declare function validateOps(rawOps: RawOp[], input: ConsolidationInput): {
+    ops: BeliefOp[];
+    rejected: {
+        op: unknown;
+        why: string;
+    }[];
+};
+export declare function slug(s: string): string;
+export {};

package/dist/consolidator.js

@@ -0,0 +1,141 @@
+const SYSTEM = `You are the memory consolidator of an AI agent — the part that "sleeps" on new experiences and turns them into durable beliefs.
+
+You receive the agent's CURRENT BELIEFS and a batch of NEW EPISODES (raw observations). Return the smallest set of operations that keeps the beliefs accurate:
+
+- create: a new belief that the episodes support. Beliefs are general, reusable knowledge — habits, schedules, preferences, relationships, rules, facts about the world. Do NOT turn every single event into a belief; one-off events only become beliefs if they are clearly important (e.g. a large unusual transfer, an explicit instruction from the user).
+- revise: an existing belief needs a new version — new evidence strengthens it (raise confidence), weakens it (lower confidence), refines it (more precise wording), or contradicts it (change the statement). Include ALL episodes that support the NEW version (old and new evidence).
+- retract: an existing belief is now clearly false or superseded and should no longer guide the agent.
+
+Rules:
+- Cite evidence ONLY with episode IDs that appear in the input (new episodes or the evidence lists of current beliefs). Never invent IDs.
+- Refer to existing beliefs ONLY by their exact id.
+- An explicit statement or correction from the user outweighs patterns inferred from data.
+- Confidence: 0.3–0.5 for a weak single-observation inference, 0.6–0.8 for a repeated pattern, 0.85–0.97 for a pattern confirmed by the user or seen many times. Never 1.0.
+- Statements are one clear sentence, specific (amounts, counterparties, timing) and in the present tense.
+- "key" for create is a short snake_case name for the belief, e.g. "rent_payment".
+- tags: 1–3 lowercase topic words (e.g. "rent", "income", "security").
+- reason: one short sentence a human auditor can read.
+- If nothing should change, return an empty list.`;
+const SCHEMA = {
+    type: "object",
+    properties: {
+        ops: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    op: { type: "string", enum: ["create", "revise", "retract"] },
+                    key: { type: "string", description: "create only: snake_case name" },
+                    belief: { type: "string", description: "revise/retract only: existing belief id" },
+                    statement: { type: "string" },
+                    confidence: { type: "number" },
+                    evidence: { type: "array", items: { type: "string" } },
+                    tags: { type: "array", items: { type: "string" } },
+                    reason: { type: "string" },
+                },
+                // Gemini's schema has no conditionals, so ask for every field; retract ignores the extras.
+                required: ["op", "statement", "confidence", "evidence", "tags", "reason"],
+            },
+        },
+    },
+    required: ["ops"],
+};
+export function buildPrompt(input) {
+    const beliefs = input.beliefs.length
+        ? input.beliefs
+            .map((b) => `- id=${b.id} v${b.version} conf=${b.confidence.toFixed(2)} tags=[${b.tags.join(",")}] evidence=[${b.evidence.join(",")}]\n  "${b.statement}"`)
+            .join("\n")
+        : "(none yet)";
+    const eps = input.episodes
+        .map((e) => `- id=${e.id} at=${new Date(e.content.ts).toISOString()} source=${e.content.source}\n  ${JSON.stringify(e.content.data)}`)
+        .join("\n");
+    return `${input.context ? `CONTEXT: ${input.context}\n\n` : ""}CURRENT BELIEFS:\n${beliefs}\n\nNEW EPISODES (${input.episodes.length}):\n${eps}\n\nReturn the operations as JSON.`;
+}
+/** Asks the LLM for belief changes and drops anything malformed or ungrounded. */
+export async function proposeOps(llm, input) {
+    const prompt = buildPrompt(input);
+    const raw = await llm.json(SYSTEM, prompt, SCHEMA);
+    const first = validateOps(raw.ops ?? [], input);
+    if (first.rejected.length === 0)
+        return first;
+    // One repair round: show the model what was rejected and why, keep whatever it fixes.
+    const feedback = first.rejected.map((r) => `- ${r.why}: ${JSON.stringify(r.op)}`).join("\n");
+    const accepted = first.ops.map((o) => JSON.stringify(o)).join("\n") || "(none)";
+    let repaired;
+    try {
+        repaired = await llm.json(SYSTEM, `${prompt}\n\nYour previous answer had operations that were REJECTED:\n${feedback}\n\nThese were ACCEPTED and are already applied — do not repeat them:\n${accepted}\n\nReturn ONLY corrected versions of the rejected operations (with valid episode IDs as evidence), or an empty list if they should be dropped.`, SCHEMA);
+    }
+    catch {
+        return first;
+    }
+    // Validate repairs against the same input, minus beliefs the first pass already touched.
+    const touched = new Set(first.ops.flatMap((o) => (o.op === "create" ? [] : [o.belief])));
+    const second = validateOps((repaired.ops ?? []).filter((o) => !o.belief || !touched.has(o.belief)), input);
+    return { ops: [...first.ops, ...second.ops], rejected: second.rejected };
+}
+export function validateOps(rawOps, input) {
+    const knownEpisodes = new Set([...input.episodes.map((e) => e.id), ...input.beliefs.flatMap((b) => b.evidence)]);
+    const knownBeliefs = new Set(input.beliefs.map((b) => b.id));
+    const touched = new Set();
+    const ops = [];
+    const rejected = [];
+    const reject = (op, why) => rejected.push({ op, why });
+    for (const r of rawOps) {
+        const reason = (r.reason ?? "").trim() || "no reason given";
+        if (r.op === "retract") {
+            if (!r.belief || !knownBeliefs.has(r.belief)) {
+                reject(r, "unknown belief");
+                continue;
+            }
+            if (touched.has(r.belief)) {
+                reject(r, "belief changed twice");
+                continue;
+            }
+            touched.add(r.belief);
+            ops.push({ op: "retract", belief: r.belief, reason });
+            continue;
+        }
+        if (r.op !== "create" && r.op !== "revise") {
+            reject(r, "unknown op");
+            continue;
+        }
+        const statement = (r.statement ?? "").trim();
+        if (!statement) {
+            reject(r, "empty statement");
+            continue;
+        }
+        const evidence = [...new Set(r.evidence ?? [])];
+        const bad = evidence.filter((e) => !knownEpisodes.has(e));
+        const good = evidence.filter((e) => knownEpisodes.has(e));
+        if (good.length === 0) {
+            reject(r, `no valid evidence${bad.length ? ` (unknown: ${bad.join(",")})` : ""}`);
+            continue;
+        }
+        const confidence = clamp(Number(r.confidence ?? 0.5), 0.01, 0.99);
+        const tags = [...new Set((r.tags ?? []).map((t) => t.toLowerCase().trim()).filter(Boolean))].slice(0, 3);
+        if (r.op === "revise") {
+            if (!r.belief || !knownBeliefs.has(r.belief)) {
+                reject(r, "unknown belief");
+                continue;
+            }
+            if (touched.has(r.belief)) {
+                reject(r, "belief changed twice");
+                continue;
+            }
+            touched.add(r.belief);
+            ops.push({ op: "revise", belief: r.belief, statement, confidence, evidence: good, tags, reason });
+        }
+        else {
+            ops.push({ op: "create", key: slug(r.key ?? statement), statement, confidence, evidence: good, tags, reason });
+        }
+    }
+    return { ops, rejected };
+}
+function clamp(x, lo, hi) {
+    return Number.isFinite(x) ? Math.min(hi, Math.max(lo, x)) : 0.5;
+}
+export function slug(s) {
+    const out = s.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 32).replace(/_+$/, "");
+    return out || "belief";
+}
+//# sourceMappingURL=consolidator.js.map

package/dist/consolidator.js.map

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

package/dist/crypto.d.ts

@@ -0,0 +1,26 @@
+import { bytesToHex, hexToBytes } from "@noble/hashes/utils.js";
+export { bytesToHex, hexToBytes };
+/**
+ * Deterministic JSON: object keys sorted, no whitespace, `undefined` fields dropped.
+ * Everything Engram hashes or signs goes through this.
+ */
+export declare function canonical(value: unknown): string;
+export declare function sha256Hex(data: string | Uint8Array): string;
+export declare function sha256Bytes(data: Uint8Array): Uint8Array;
+export declare function randomId(prefix: string, bytes?: number): string;
+export interface KeyPair {
+    secretKey: string;
+    publicKey: string;
+}
+export declare function generateKeyPair(): KeyPair;
+export declare function publicKeyOf(secretKeyHex: string): string;
+export declare function sign(message: string, secretKeyHex: string): string;
+export declare function verifySignature(message: string, signatureHex: string, publicKeyHex: string): boolean;
+export interface Sealed {
+    iv: string;
+    ct: string;
+    tag: string;
+}
+export declare function newDataKey(): Buffer;
+export declare function encrypt(plaintext: Uint8Array, key: Uint8Array, aad?: string): Sealed;
+export declare function decrypt(sealed: Sealed, key: Uint8Array, aad?: string): Buffer;

package/dist/crypto.js

@@ -0,0 +1,72 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { bytesToHex, hexToBytes, utf8ToBytes } from "@noble/hashes/utils.js";
+import { ed25519 } from "@noble/curves/ed25519.js";
+export { bytesToHex, hexToBytes };
+/**
+ * Deterministic JSON: object keys sorted, no whitespace, `undefined` fields dropped.
+ * Everything Engram hashes or signs goes through this.
+ */
+export function canonical(value) {
+    return JSON.stringify(sortValue(value));
+}
+function sortValue(v) {
+    if (Array.isArray(v))
+        return v.map(sortValue);
+    if (v && typeof v === "object") {
+        const out = {};
+        for (const k of Object.keys(v).sort()) {
+            const x = v[k];
+            if (x !== undefined)
+                out[k] = sortValue(x);
+        }
+        return out;
+    }
+    return v;
+}
+export function sha256Hex(data) {
+    return bytesToHex(sha256(typeof data === "string" ? utf8ToBytes(data) : data));
+}
+export function sha256Bytes(data) {
+    return sha256(data);
+}
+export function randomId(prefix, bytes = 6) {
+    return `${prefix}_${randomBytes(bytes).toString("hex")}`;
+}
+export function generateKeyPair() {
+    const sk = ed25519.utils.randomSecretKey();
+    return { secretKey: bytesToHex(sk), publicKey: bytesToHex(ed25519.getPublicKey(sk)) };
+}
+export function publicKeyOf(secretKeyHex) {
+    return bytesToHex(ed25519.getPublicKey(hexToBytes(secretKeyHex)));
+}
+export function sign(message, secretKeyHex) {
+    return bytesToHex(ed25519.sign(utf8ToBytes(message), hexToBytes(secretKeyHex)));
+}
+export function verifySignature(message, signatureHex, publicKeyHex) {
+    try {
+        return ed25519.verify(hexToBytes(signatureHex), utf8ToBytes(message), hexToBytes(publicKeyHex));
+    }
+    catch {
+        return false;
+    }
+}
+export function newDataKey() {
+    return randomBytes(32);
+}
+export function encrypt(plaintext, key, aad) {
+    const iv = randomBytes(12);
+    const c = createCipheriv("aes-256-gcm", key, iv);
+    if (aad)
+        c.setAAD(Buffer.from(aad, "utf8"));
+    const ct = Buffer.concat([c.update(plaintext), c.final()]);
+    return { iv: iv.toString("base64"), ct: ct.toString("base64"), tag: c.getAuthTag().toString("base64") };
+}
+export function decrypt(sealed, key, aad) {
+    const d = createDecipheriv("aes-256-gcm", key, Buffer.from(sealed.iv, "base64"));
+    if (aad)
+        d.setAAD(Buffer.from(aad, "utf8"));
+    d.setAuthTag(Buffer.from(sealed.tag, "base64"));
+    return Buffer.concat([d.update(Buffer.from(sealed.ct, "base64")), d.final()]);
+}
+//# sourceMappingURL=crypto.js.map

package/dist/crypto.js.map

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

package/dist/engram.d.ts

@@ -0,0 +1,266 @@
+import { LocalStore } from "./store.js";
+import { KeyVault } from "./vault.js";
+import type { RemoteMemory } from "./remote.js";
+import type { LLM } from "./llm.js";
+import { type BeliefOp } from "./consolidator.js";
+import type { Anchorer } from "./anchor.js";
+import type { Belief, Commit, CommitManifest, Episode, EpisodeContent, EpisodeSource, Receipt } from "./types.js";
+export interface Check {
+    name: string;
+    ok: boolean;
+    detail: string;
+    /** Skipped checks (e.g. no network) don't fail the report but are shown. */
+    skipped?: boolean;
+}
+export interface VerifyReport {
+    ok: boolean;
+    checks: Check[];
+}
+export interface VerifyOptions {
+    /** Also confirm the manifest on Walrus Memory (network). Default true. */
+    walrus?: boolean;
+    /** Also confirm the anchor on Sui via the anchorer (network). Default true. */
+    chain?: boolean;
+}
+export interface DecideInput {
+    action: string;
+    /** What the agent was asked / saw. Only its hash is stored. */
+    input: unknown;
+    /** Beliefs the decision relied on: "b_x" (version in HEAD) or "b_x@2". */
+    beliefs: string[];
+}
+export interface ForgetResult {
+    episode: Episode;
+    revised: Belief[];
+    retracted: Belief[];
+}
+export declare class NothingToCommitError extends Error {
+    constructor(first?: boolean);
+}
+export interface BeliefDiff {
+    added: Belief[];
+    /** [before, after] */
+    changed: [Belief, Belief][];
+    removed: Belief[];
+}
+export interface BisectResult {
+    /** First commit where the agent behaves badly. */
+    commit: Commit;
+    /** What that commit changed — the likely culprit. */
+    diff: BeliefDiff;
+    steps: {
+        commit: string;
+        bad: boolean;
+    }[];
+    tested: number;
+    candidates: number;
+}
+export interface BlameEntry {
+    episode: Episode;
+    /** Decrypted content, or null if forgotten. */
+    content: EpisodeContent | null;
+}
+/** "b_rent@2" */
+export declare const beliefKey: (b: Pick<Belief, "id" | "version">) => string;
+export interface SleepOptions {
+    llm: LLM;
+    /** Domain hint for the consolidator. */
+    context?: string;
+    /** Episodes per LLM call. Default 40. */
+    batchSize?: number;
+}
+export interface SleepReport {
+    episodes: number;
+    created: Belief[];
+    revised: Belief[];
+    retracted: Belief[];
+    rejected: {
+        op: unknown;
+        why: string;
+    }[];
+}
+export interface EngramConfig {
+    v: 1;
+    agent: string;
+    agentPubKey: string;
+    createdAt: number;
+    namespaces: {
+        episodes: string;
+        beliefs: string;
+        commits: string;
+        receipts: string;
+    };
+}
+export interface OpenOptions {
+    /** Folder that contains (or will contain) `.engram/`. Default: cwd. */
+    dir?: string;
+    remote: RemoteMemory;
+    /** Finds the on-chain anchor for commits. Without one, commits are signed but unanchored. */
+    anchorer?: Anchorer;
+    /**
+     * Open without the agent's keys (e.g. a repo rebuilt from an audit bundle):
+     * history, beliefs, receipts and verification work; signing and decrypting don't.
+     */
+    readOnly?: boolean;
+}
+export interface ObserveInput {
+    source: EpisodeSource;
+    data: unknown;
+    /** Short label shown in logs. Stored in the clear locally — keep it non-sensitive. */
+    summary?: string;
+    ts?: number;
+}
+export interface PushResult {
+    episodes: number;
+    beliefs: number;
+    receipts: number;
+}
+export declare class Engram {
+    readonly store: LocalStore;
+    readonly vault: KeyVault;
+    readonly config: EngramConfig;
+    readonly remote: RemoteMemory;
+    readonly anchorer?: Anchorer;
+    private secretKey;
+    /** True when opened without keys — nothing can be signed or decrypted. */
+    readonly readOnly: boolean;
+    private constructor();
+    /** Creates `.engram/` with a fresh agent signing key and master key. */
+    static init(agent: string, opts: OpenOptions): Engram;
+    static open(opts: OpenOptions): Engram;
+    get agent(): string;
+    get publicKey(): string;
+    /** Signs with the agent key (commits and receipts). */
+    protected signRaw(message: string): string;
+    /** Records a raw event, encrypted with its own key. Stored locally; `push()` uploads it. */
+    observe(input: ObserveInput): Episode;
+    episodes(): Episode[];
+    episode(id: string): Episode | null;
+    /** Decrypts an episode. Returns null if it was forgotten. Throws if it was tampered with. */
+    read(id: string): EpisodeContent | null;
+    /** Every version of every belief, oldest first. */
+    beliefVersions(): Belief[];
+    /** Latest version of each belief, including retracted ones. */
+    latestBeliefs(): Belief[];
+    /** The beliefs that currently guide the agent. */
+    beliefs(): Belief[];
+    /** A belief by "b_x" (latest) or "b_x@2" (exact version). */
+    belief(ref: string): Belief | null;
+    /** All versions of one belief, oldest first. */
+    history(id: string): Belief[];
+    /** Episodes that `sleep()` has not processed yet (forgotten ones are skipped). */
+    pendingEpisodes(): Episode[];
+    /**
+     * Consolidation: new episodes + current beliefs → belief changes, via the LLM.
+     * Every change is a new immutable belief version with evidence and a reason.
+     */
+    sleep(opts: SleepOptions): Promise<SleepReport>;
+    /** Applies one belief change. Exposed so users (and tests) can edit beliefs by hand. */
+    applyOp(op: BeliefOp): Belief;
+    /**
+     * Beliefs relevant to a task. Uses Walrus Memory semantic recall over pushed
+     * beliefs, then falls back to keyword matching for anything not pushed yet.
+     */
+    relevant(query: string, limit?: number): Promise<Belief[]>;
+    /** Current commit ID, or null before the first commit. */
+    head(): string | null;
+    getCommit(id: string): Commit | null;
+    /** IDs of forgotten episodes, sorted. */
+    tombstones(): string[];
+    /**
+     * Snapshot of the current beliefs: push pending data, build the Merkle root,
+     * sign the manifest, store it on Walrus Memory and look up its Sui anchor.
+     */
+    commit(message: string, opts?: {
+        allowEmpty?: boolean;
+    }): Promise<Commit>;
+    /** Looks up (or retries looking up) the Sui anchor of a commit. */
+    anchor(id: string): Promise<Commit>;
+    /** Commits from HEAD back to the first one. */
+    log(from?: string): Commit[];
+    /**
+     * Resolves "HEAD", "HEAD~2", a full or short (≥4 chars) commit ID, or a
+     * date ("2026-10-25") → the last commit made at or before it.
+     */
+    resolve(ref: string): string;
+    /** The beliefs the agent had at a commit — time travel. */
+    beliefsAt(ref: string): Belief[];
+    /** What changed between two commits (or a commit and the working beliefs when `to` is omitted). */
+    diff(from: string, to?: string): BeliefDiff;
+    /**
+     * Binary search over history: given a commit where the agent behaved well
+     * and a later one where it didn't, finds the first bad commit. `isBad`
+     * receives the beliefs at a commit (time travel) — run the agent's test there.
+     */
+    bisect(opts: {
+        good: string;
+        bad: string;
+        isBad: (beliefs: Belief[], commit: Commit) => Promise<boolean> | boolean;
+    }): Promise<BisectResult>;
+    /** The episodes behind a belief version, decrypted where possible. */
+    blame(ref: string): {
+        belief: Belief;
+        history: Belief[];
+        evidence: BlameEntry[];
+    };
+    /**
+     * In a read-only repo rebuilt from an audit bundle the raw episodes aren't
+     * present (they stay with the agent). Commits still record each evidence
+     * episode's Walrus blob ID, so blame can point at it.
+     */
+    private sharedEpisodeStub;
+    /**
+     * Records a signed receipt for a decision: which committed beliefs it used,
+     * with Merkle proofs that they were in the HEAD commit.
+     */
+    decide(input: DecideInput): Receipt;
+    /**
+     * The runtime hook: gives `fn` the committed beliefs relevant to `task`,
+     * then records a signed receipt for what it decided and which beliefs it used.
+     * Before the first commit, `fn` gets no beliefs and no receipt is written.
+     */
+    act<T>(task: {
+        query: string;
+        input: unknown;
+        limit?: number;
+    }, fn: (beliefs: Belief[]) => Promise<{
+        action: string;
+        used: string[];
+        result: T;
+    }> | {
+        action: string;
+        used: string[];
+        result: T;
+    }): Promise<{
+        result: T;
+        action: string;
+        receipt: Receipt | null;
+        beliefs: Belief[];
+    }>;
+    receipts(): Receipt[];
+    receipt(id: string): Receipt | null;
+    /**
+     * Checks a commit end to end: ID, signature, Merkle root rebuilt from the
+     * beliefs, the parent chain, the manifest on Walrus Memory, and the Sui anchor.
+     */
+    verifyCommit(ref: string, opts?: VerifyOptions): Promise<VerifyReport>;
+    /** Checks a receipt: its signature, each belief's Merkle proof, then the commit it points at. */
+    verifyReceipt(id: string, opts?: VerifyOptions): Promise<VerifyReport>;
+    /**
+     * Crypto-shredding: destroys the episode's key so its ciphertext (local and
+     * on Walrus) can never be decrypted again. Beliefs that relied on it lose
+     * that evidence — and are retracted if nothing else supports them. The next
+     * commit records a tombstone.
+     */
+    forget(episodeId: string, reason?: string): ForgetResult;
+    /** Uploads everything not yet on Walrus Memory and records the blob IDs. */
+    push(): Promise<PushResult>;
+}
+/** How a belief is written to Walrus Memory: readable statement first (for semantic recall), then the full record. */
+export declare function beliefText(b: Belief): string;
+/** Returns "id@version" from a belief text, or null if it isn't one. */
+export declare function parseBeliefText(text: string): string | null;
+/** How a commit is written to Walrus Memory. */
+export declare function commitText(id: string, manifest: CommitManifest, signature: string): string;
+/** How a receipt is written to Walrus Memory. */
+export declare function receiptText(r: Receipt): string;