purra-mem0 0.5.0

package/dist/journal.js

@@ -0,0 +1,301 @@
+import { DatabaseSync } from "node:sqlite";
+import { randomUUID } from "node:crypto";
+export class MemoryError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = "MemoryError";
+    }
+}
+export function itemView(row) {
+    return { version: row.meta.purra_version, state: row.meta.purra_state,
+        metadata: row.meta.purra_metadata, reason: row.meta.purra_reason,
+        createdAt: row.meta.purra_created, updatedAt: row.meta.purra_updated, ...row.view };
+}
+/** Only control metadata is stored here. Content and vectors remain in Mem0. */
+export class Journal {
+    scope;
+    db;
+    store;
+    constructor(path, scope) {
+        this.scope = scope;
+        if (typeof path !== "string" || !path.trim() || path === ":memory:") {
+            throw new TypeError("journalPath must be a persistent SQLite path");
+        }
+        this.db = new DatabaseSync(path);
+        this.db.exec(`
+      PRAGMA busy_timeout=5000;
+      CREATE TABLE IF NOT EXISTS purra_mem0_info (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS purra_mem0_epochs (scope TEXT PRIMARY KEY, epoch INTEGER NOT NULL);
+      CREATE TABLE IF NOT EXISTS purra_mem0_ops (
+        scope TEXT NOT NULL, key TEXT NOT NULL, fingerprint TEXT NOT NULL,
+        state TEXT NOT NULL, plan TEXT NOT NULL, ids TEXT, PRIMARY KEY(scope,key));
+      CREATE UNIQUE INDEX IF NOT EXISTS purra_mem0_writer ON purra_mem0_ops(scope)
+        WHERE state IN ('running','unknown');
+      CREATE TABLE IF NOT EXISTS purra_mem0_items (
+        scope TEXT NOT NULL, id TEXT NOT NULL, record TEXT NOT NULL, PRIMARY KEY(scope,id));
+      CREATE TABLE IF NOT EXISTS purra_mem0_budgets (
+        scope TEXT NOT NULL, key TEXT NOT NULL, limits TEXT NOT NULL, PRIMARY KEY(scope,key));
+      CREATE TABLE IF NOT EXISTS purra_mem0_calls (
+        scope TEXT NOT NULL, id TEXT NOT NULL, budget TEXT NOT NULL, operation TEXT,
+        kind TEXT NOT NULL, state TEXT NOT NULL, input_chars INTEGER NOT NULL,
+        reserved_output INTEGER NOT NULL, input_tokens INTEGER, output_tokens INTEGER,
+        PRIMARY KEY(scope,id));
+      CREATE INDEX IF NOT EXISTS purra_mem0_calls_budget ON purra_mem0_calls(scope,budget);
+      CREATE INDEX IF NOT EXISTS purra_mem0_calls_operation ON purra_mem0_calls(scope,operation);
+      CREATE TABLE IF NOT EXISTS purra_mem0_revocations (
+        scope TEXT NOT NULL, source TEXT NOT NULL, revision TEXT NOT NULL,
+        PRIMARY KEY(scope,source,revision));
+    `);
+        this.transaction(() => {
+            this.db.prepare("INSERT OR IGNORE INTO purra_mem0_info VALUES ('store',?)").run(randomUUID().replaceAll("-", ""));
+            this.db.prepare("INSERT OR IGNORE INTO purra_mem0_epochs VALUES (?,0)").run(scope);
+        });
+        this.store = this.db.prepare("SELECT value FROM purra_mem0_info WHERE key='store'").get().value;
+    }
+    transaction(work) {
+        this.db.exec("BEGIN IMMEDIATE");
+        try {
+            const result = work();
+            this.db.exec("COMMIT");
+            return result;
+        }
+        catch (error) {
+            this.db.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    operation(key) {
+        const row = this.db.prepare("SELECT * FROM purra_mem0_ops WHERE scope=? AND key=?").get(this.scope, key);
+        if (!row)
+            return undefined;
+        return { key, fingerprint: row.fingerprint, state: row.state,
+            plan: JSON.parse(row.plan), ids: row.ids === null ? null : JSON.parse(row.ids) };
+    }
+    begin(key, fingerprint, plan) {
+        return this.transaction(() => {
+            const previous = this.operation(key);
+            if (previous) {
+                if (previous.fingerprint !== fingerprint)
+                    throw new MemoryError("memory_idempotency_conflict");
+                return previous;
+            }
+            if (this.db.prepare("SELECT 1 FROM purra_mem0_ops WHERE scope=? AND state IN ('running','unknown')").get(this.scope)) {
+                throw new MemoryError("memory_write_busy");
+            }
+            this.db.prepare("INSERT INTO purra_mem0_ops VALUES (?,?,?,'running',?,NULL)")
+                .run(this.scope, key, fingerprint, JSON.stringify(plan));
+            return undefined;
+        });
+    }
+    savePlan(key, plan) {
+        this.db.prepare("UPDATE purra_mem0_ops SET plan=? WHERE scope=? AND key=?").run(JSON.stringify(plan), this.scope, key);
+    }
+    saveIds(key, ids) {
+        this.db.prepare("UPDATE purra_mem0_ops SET ids=? WHERE scope=? AND key=?").run(JSON.stringify(ids), this.scope, key);
+    }
+    budget(key, limits) {
+        this.transaction(() => {
+            const row = this.db.prepare("SELECT limits FROM purra_mem0_budgets WHERE scope=? AND key=?").get(this.scope, key);
+            if (row) {
+                const previous = JSON.parse(row.limits);
+                if (Object.keys(previous).length !== Object.keys(limits).length || Object.entries(limits).some(([k, v]) => previous[k] !== v)) {
+                    throw new MemoryError("memory_budget_conflict");
+                }
+            }
+            this.db.prepare("INSERT OR IGNORE INTO purra_mem0_budgets VALUES (?,?,?)").run(this.scope, key, JSON.stringify(limits));
+        });
+    }
+    usage(column, key) {
+        const row = this.db.prepare(`SELECT
+      COALESCE(SUM(kind='llm'),0) AS llmCalls,
+      COALESCE(SUM(kind='embedding'),0) AS embeddingCalls,
+      COALESCE(SUM(input_chars),0) AS inputChars,
+      COALESCE(SUM(reserved_output),0) AS reservedOutputTokens,
+      COALESCE(SUM(input_tokens),0) AS reportedInputTokens,
+      COALESCE(SUM(output_tokens),0) AS reportedOutputTokens,
+      COALESCE(SUM(input_tokens IS NULL OR output_tokens IS NULL),0) AS unreportedCalls,
+      COALESCE(SUM(state='started'),0) AS unsettledCalls
+      FROM purra_mem0_calls WHERE scope=? AND ${column}=?`).get(this.scope, key);
+        return Object.freeze(row);
+    }
+    admit(budget, operation, kind, chars, reserve) {
+        return this.transaction(() => {
+            const op = operation === undefined ? undefined : this.operation(operation);
+            if (op?.plan.kind === "review")
+                this.assertSnapshot(op.plan);
+            if (op && op.plan.kind !== "delete" && op.plan.meta)
+                this.assertSource(op.plan.meta);
+            const limits = JSON.parse(this.db.prepare("SELECT limits FROM purra_mem0_budgets WHERE scope=? AND key=?").get(this.scope, budget).limits);
+            const used = this.usage("budget", budget);
+            if (used[kind === "llm" ? "llmCalls" : "embeddingCalls"] + 1 > limits["max_" + kind + "_calls"]
+                || used.inputChars + chars > limits.max_input_chars
+                || used.reservedOutputTokens + reserve > limits.max_output_tokens)
+                throw new MemoryError("memory_budget_exceeded");
+            const id = randomUUID().replaceAll("-", "");
+            this.db.prepare("INSERT INTO purra_mem0_calls VALUES (?,?,?,?,?,'started',?,?,NULL,NULL)")
+                .run(this.scope, id, budget, operation ?? null, kind, chars, reserve);
+            return id;
+        });
+    }
+    settle(id, state, inputTokens = null, generationTokens = null) {
+        this.db.prepare("UPDATE purra_mem0_calls SET state=?,input_tokens=?,output_tokens=? WHERE scope=? AND id=?")
+            .run(state, inputTokens, generationTokens, this.scope, id);
+    }
+    providerError(key, code) {
+        this.transaction(() => {
+            const op = this.operation(key);
+            if (op)
+                this.savePlan(key, { ...op.plan, provider_error: code });
+        });
+    }
+    verifyProviders(key) {
+        this.transaction(() => {
+            const op = this.operation(key);
+            this.savePlan(key, { ...op.plan, providers_verified: true });
+        });
+    }
+    fail(key, dispatched) {
+        this.db.prepare("UPDATE purra_mem0_ops SET state=? WHERE scope=? AND key=?").run(dispatched ? "unknown" : "failed", this.scope, key);
+    }
+    discard(key) {
+        this.db.prepare("UPDATE purra_mem0_ops SET state='discarded' WHERE scope=? AND key=?").run(this.scope, key);
+    }
+    revoked(source, revision) {
+        return !!this.db.prepare("SELECT 1 FROM purra_mem0_revocations WHERE scope=? AND source=? AND revision IN ('',?)")
+            .get(this.scope, source, revision);
+    }
+    assertSource(meta) {
+        if (this.revoked(meta.purra_source, meta.purra_revision))
+            throw new MemoryError("memory_source_revoked");
+    }
+    revokeSource(key, fingerprint, source, revision) {
+        // An uncertain SDK writer must not block withdrawal; its fence stays intact.
+        this.transaction(() => {
+            const previous = this.operation(key);
+            if (previous) {
+                if (previous.fingerprint !== fingerprint)
+                    throw new MemoryError("memory_idempotency_conflict");
+                return;
+            }
+            const plan = { kind: "revoke_source", target: null, meta: null, source, revision };
+            this.db.prepare("INSERT INTO purra_mem0_ops VALUES (?,?,?,'complete',?,'[]')").run(this.scope, key, fingerprint, JSON.stringify(plan));
+            if (!this.revoked(source, revision ?? "")) {
+                this.db.prepare("INSERT INTO purra_mem0_revocations VALUES (?,?,?)").run(this.scope, source, revision ?? "");
+                this.db.prepare("UPDATE purra_mem0_epochs SET epoch=epoch+1 WHERE scope=?").run(this.scope);
+            }
+        });
+    }
+    item(id) {
+        const row = this.db.prepare("SELECT record FROM purra_mem0_items WHERE scope=? AND id=?").get(this.scope, id);
+        return row ? JSON.parse(row.record) : undefined;
+    }
+    resolve(key, fingerprint, plan, epoch) {
+        const resolution = plan.resolution;
+        this.control(key, fingerprint, plan, epoch, resolution.items, resolution.items.map(ref => ({
+            state: ref.id === resolution.keep ? "active" : "disabled",
+            reason: ref.id === resolution.keep ? null : resolution.kind, resolution: key,
+        })));
+    }
+    control(key, fingerprint, plan, epoch, refs, changes) {
+        this.transaction(() => {
+            const previous = this.operation(key);
+            if (previous) {
+                if (previous.fingerprint !== fingerprint)
+                    throw new MemoryError("memory_idempotency_conflict");
+                return;
+            }
+            if (this.db.prepare("SELECT 1 FROM purra_mem0_ops WHERE scope=? AND state IN ('running','unknown')").get(this.scope))
+                throw new MemoryError("memory_write_busy");
+            if (this.epoch !== epoch)
+                throw new MemoryError("memory_context_stale");
+            if (plan.review_key !== undefined)
+                this.assertSnapshot(this.reviewPlan(plan.review_key));
+            const records = [], now = Date.now();
+            for (const [index, ref] of refs.entries()) {
+                const row = this.item(ref.id);
+                if (!row || row.deleted)
+                    throw new MemoryError("memory_not_found");
+                if (itemView(row).version !== ref.version)
+                    throw new MemoryError("memory_version_conflict");
+                this.assertSource(row.meta);
+                if ((["resolve", "link"].includes(plan.kind) || changes[index]?.state === "active")
+                    && row.meta.purra_expires !== null && Date.parse(row.meta.purra_expires) <= now)
+                    throw new MemoryError("memory_context_stale");
+                if (changes[index])
+                    row.view = { ...itemView(row), ...changes[index], version: ref.version + 1, updatedAt: new Date(now).toISOString() };
+                records.push(row);
+            }
+            this.db.prepare("INSERT INTO purra_mem0_ops VALUES (?,?,?,'complete',?,?)")
+                .run(this.scope, key, fingerprint, JSON.stringify(plan), JSON.stringify(records.map(r => r.id)));
+            for (const row of records)
+                this.db.prepare("UPDATE purra_mem0_items SET record=? WHERE scope=? AND id=?").run(JSON.stringify(row), this.scope, row.id);
+            this.db.prepare("UPDATE purra_mem0_epochs SET epoch=epoch+1 WHERE scope=?").run(this.scope);
+        });
+    }
+    assertSnapshot(plan) {
+        if (plan.review_epoch !== this.epoch || !plan.review_refs?.length)
+            throw new MemoryError("memory_context_stale");
+        const now = Date.now();
+        for (const ref of plan.review_refs) {
+            const row = this.item(ref.id);
+            if (!row || row.deleted || itemView(row).version !== ref.version)
+                throw new MemoryError("memory_context_stale");
+            this.assertSource(row.meta);
+            if (row.meta.purra_expires !== null && Date.parse(row.meta.purra_expires) <= now)
+                throw new MemoryError("memory_context_stale");
+        }
+    }
+    links(id, after, limit) {
+        return this.db.prepare(`SELECT key,plan FROM purra_mem0_ops WHERE scope=? AND key>? AND state='complete'
+      AND json_extract(plan,'$.kind')='link'
+      AND (json_extract(plan,'$.link.from.id')=? OR json_extract(plan,'$.link.to.id')=?)
+      ORDER BY key LIMIT ?`).all(this.scope, after ?? "", id, id, limit)
+            .map(row => ({ key: row.key, data: JSON.parse(row.plan).link }));
+    }
+    reviewPlan(key) {
+        const op = this.operation(key);
+        if (!op || op.state !== "complete" || op.plan.kind !== "review" || !op.plan.review)
+            throw new MemoryError("memory_review_unavailable");
+        return op.plan;
+    }
+    finishReview(key, plan) {
+        this.transaction(() => {
+            if (this.operation(key)?.state !== "running")
+                throw new MemoryError("memory_operation_unresolved");
+            this.assertSnapshot(plan);
+            this.savePlan(key, plan);
+            this.db.prepare("UPDATE purra_mem0_ops SET state='complete',ids='[]' WHERE scope=? AND key=?").run(this.scope, key);
+        });
+    }
+    items(state, after, limit) {
+        return this.db.prepare(`SELECT record FROM purra_mem0_items AS item WHERE scope=? AND id>?
+      AND json_extract(record,'$.deleted')=0
+      AND (? IS NULL OR COALESCE(json_extract(record,'$.view.state'),json_extract(record,'$.meta.purra_state'))=?)
+      AND NOT EXISTS (SELECT 1 FROM purra_mem0_revocations AS r
+        WHERE r.scope=item.scope AND r.source=json_extract(item.record,'$.meta.purra_source')
+        AND r.revision IN ('',json_extract(item.record,'$.meta.purra_revision')))
+      AND (? IS NULL OR ? != 'active' OR json_extract(record,'$.meta.purra_expires') IS NULL
+           OR json_extract(record,'$.meta.purra_expires')>?) ORDER BY id LIMIT ?`)
+            .all(this.scope, after ?? "", state, state, state, state, new Date().toISOString(), limit)
+            .map(row => JSON.parse(row.record));
+    }
+    writing(id) {
+        return this.db.prepare("SELECT plan FROM purra_mem0_ops WHERE scope=? AND state IN ('running','unknown')").all(this.scope)
+            .some(row => JSON.parse(row.plan).target === id);
+    }
+    commit(key, records) {
+        this.transaction(() => {
+            for (const record of records)
+                this.db.prepare("INSERT OR REPLACE INTO purra_mem0_items VALUES (?,?,?)").run(this.scope, record.id, JSON.stringify(record));
+            this.db.prepare("UPDATE purra_mem0_ops SET state='complete' WHERE scope=? AND key=?").run(this.scope, key);
+            if (records.length)
+                this.db.prepare("UPDATE purra_mem0_epochs SET epoch=epoch+1 WHERE scope=?").run(this.scope);
+        });
+    }
+    get epoch() {
+        return this.db.prepare("SELECT epoch FROM purra_mem0_epochs WHERE scope=?").get(this.scope).epoch;
+    }
+    close() { this.db.close(); }
+}

package/dist/memory.d.ts

@@ -0,0 +1,213 @@
+import type { ContextEvidenceReceipt, RetrievalHit, RetrievalRequest, Retriever } from "purra";
+import type { MemoryProviders, MemoryUsage } from "./providers.js";
+/** Structurally satisfied by `Memory` from `mem0ai/oss` 3.1.7. */
+export interface Mem0Client {
+    add(messages: string | {
+        role: string;
+        content: string;
+    }[], options: {
+        userId: string;
+        runId: string;
+        metadata: Record<string, unknown>;
+        infer: boolean;
+    }): Promise<unknown>;
+    get(id: string): Promise<unknown>;
+    getAll(options: {
+        filters: Record<string, unknown>;
+        topK: number;
+    }): Promise<unknown>;
+    search(query: string, options: {
+        filters: Record<string, unknown>;
+        topK: number;
+    }): Promise<unknown>;
+    update(id: string, options: {
+        text: string;
+        metadata: Record<string, unknown>;
+    }): Promise<unknown>;
+    delete(id: string): Promise<unknown>;
+    history(id: string): Promise<unknown>;
+}
+export interface MemoryScope {
+    readonly user: string;
+    readonly project: string;
+    readonly agent?: string;
+}
+export interface MemorySource {
+    readonly id: string;
+    readonly revision: string;
+}
+export type MemoryMetadata = Readonly<Record<string, string | number | boolean | null>>;
+export type MemoryFilters = Readonly<Record<string, string | number | boolean | null | readonly (string | number | boolean | null)[]>>;
+export interface MemoryRecord {
+    readonly id: string;
+    readonly text: string;
+    readonly version: number;
+    readonly state: "active" | "pending" | "disabled";
+    readonly source: MemorySource;
+    readonly inferred: boolean;
+    readonly expiresAt: string | null;
+    readonly resolutionKey?: string;
+    readonly metadata: MemoryMetadata;
+    readonly reason: string | null;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+export interface MemoryPage {
+    readonly items: readonly MemoryRecord[];
+    readonly next: string | null;
+    readonly epoch: number;
+}
+export interface MemoryRef {
+    readonly id: string;
+    readonly version: number;
+}
+export interface MemoryLink {
+    readonly key: string;
+    readonly from: MemoryRef;
+    readonly to: MemoryRef;
+    readonly relation: string;
+    readonly note: string;
+    readonly valid: boolean;
+}
+export interface MemoryLinkPage {
+    readonly items: readonly MemoryLink[];
+    readonly next: string | null;
+    readonly epoch: number;
+}
+export type MemoryResolution = {
+    readonly items: readonly MemoryRef[];
+    readonly reviewKey?: string;
+} & ({
+    readonly kind: "independent" | "duplicate" | "supersede";
+    readonly keep: string;
+} | {
+    readonly kind: "conflict";
+    readonly keep?: never;
+});
+export interface MemoryMatch {
+    readonly item: MemoryRef;
+    readonly kind: "independent" | "duplicate" | "supersede" | "conflict" | "uncertain";
+}
+export interface MemoryReview {
+    readonly key: string;
+    readonly candidate: MemoryRef;
+    readonly matches: readonly MemoryMatch[];
+    readonly epoch: number;
+    readonly proposal?: MemoryResolution;
+}
+export interface MemoryOperation {
+    readonly key: string;
+    readonly state: "running" | "unknown" | "failed" | "complete" | "discarded";
+    readonly ids: readonly string[];
+    readonly usage: MemoryUsage | "unknown";
+    readonly resolution?: MemoryResolution;
+    readonly review?: MemoryReview;
+}
+interface WriteOptions {
+    readonly key: string;
+    readonly signal?: AbortSignal;
+}
+interface SourceOptions extends WriteOptions {
+    readonly source: MemorySource;
+    readonly expiresAt?: string | null;
+    readonly metadata?: MemoryMetadata;
+}
+interface VersionOptions extends WriteOptions {
+    readonly version: number;
+}
+export declare function requiredText(value: unknown, label: string, limit?: number): string;
+export declare function positiveInteger(value: number, label: string, maximum?: number): number;
+/** Host-owned SDK, immutable scope, persistent write fence. No automatic capture. */
+export declare class Mem0Memory implements Retriever {
+    #private;
+    constructor(options: {
+        client: Mem0Client;
+        scope: MemoryScope;
+        journalPath: string;
+        allowInference?: boolean;
+        timeoutMs?: number;
+        maxResults?: number;
+        maxInputChars?: number;
+        providers?: MemoryProviders;
+    });
+    operation(key: string): MemoryOperation | undefined;
+    /** Verify content, then atomically keep one claim or quarantine a group. No SDK mutations. */
+    resolve(value: MemoryResolution, options: WriteOptions): Promise<MemoryOperation>;
+    /** Budgeted advice for a pending candidate; never activates memory. */
+    link(from: MemoryRef, to: MemoryRef, relation: string, options: WriteOptions & {
+        note?: string;
+    }): Promise<MemoryOperation>;
+    links(id: string, options?: {
+        limit?: number;
+        after?: string;
+        signal?: AbortSignal;
+    }): Promise<MemoryLinkPage>;
+    review(candidate: MemoryRef, options: WriteOptions & {
+        limit?: number;
+        instructions?: string;
+    }): Promise<MemoryOperation>;
+    /** Includes searches, reservations, late completions and unknown usage. */
+    budgetUsage(): MemoryUsage | undefined;
+    get epoch(): number;
+    assertEpoch(epoch: number): void;
+    /** Permanently stop using a revision, or all revisions when omitted. No physical erasure. */
+    revokeSource(sourceId: string, options: {
+        key: string;
+        revision?: string;
+        signal?: AbortSignal;
+    }): Promise<MemoryOperation>;
+    isSourceRevoked(source: MemorySource): boolean;
+    /** Revalidate all host-persisted memory receipts before reuse/resume; no inference or checkpoint rewriting. */
+    validateEvidence(receipts: readonly ContextEvidenceReceipt[], options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    get(id: string, options?: {
+        includeInactive?: boolean;
+        signal?: AbortSignal;
+    }): Promise<MemoryRecord | undefined>;
+    select(ids: readonly string[], options?: {
+        signal?: AbortSignal;
+    }): Promise<readonly RetrievalHit[]>;
+    list(options?: {
+        state?: "active" | "pending" | "disabled" | null;
+        limit?: number;
+        after?: string;
+        filters?: MemoryFilters;
+        source?: string;
+        query?: string;
+        scanLimit?: number;
+        signal?: AbortSignal;
+    }): Promise<MemoryPage>;
+    add(text: string, options: SourceOptions & {
+        state?: MemoryRecord["state"];
+        reason?: string | null;
+    }): Promise<MemoryOperation>;
+    extract(messages: readonly {
+        role: "user" | "assistant";
+        content: string;
+    }[], options: SourceOptions): Promise<MemoryOperation>;
+    update(id: string, text: string, options: SourceOptions & VersionOptions): Promise<MemoryOperation>;
+    setState(id: string, state: MemoryRecord["state"], options: VersionOptions & {
+        reason?: string | null;
+    }): Promise<MemoryOperation>;
+    annotate(id: string, metadata: MemoryMetadata, options: VersionOptions): Promise<MemoryOperation>;
+    /** Delete live content, not SDK history, source messages or checkpoints. */
+    delete(id: string, options: VersionOptions): Promise<MemoryOperation>;
+    reconcile(key: string, options?: {
+        writerStopped?: boolean;
+        signal?: AbortSignal;
+    }): Promise<MemoryOperation>;
+    discardExtraction(key: string, options?: {
+        writerStopped?: boolean;
+        signal?: AbortSignal;
+    }): Promise<MemoryOperation>;
+    history(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<readonly unknown[]>;
+    retrieve(request: RetrievalRequest, signal?: AbortSignal, options?: {
+        filters?: MemoryFilters;
+    }): Promise<readonly RetrievalHit[]>;
+    drain(): Promise<void>;
+    close(): void;
+}
+export {};