purra-mem0 0.5.0

package/dist/providers.d.ts

@@ -0,0 +1,80 @@
+import type { Message, ModelTaskRunner, ModelTurn } from "purra";
+import { Journal } from "./journal.js";
+import type { Mem0Client } from "./memory.js";
+/** Durable per-namespace envelope. Reservations are never refunded. */
+export interface MemoryBudget {
+    readonly key: string;
+    readonly maxLlmCalls: number;
+    readonly maxEmbeddingCalls: number;
+    readonly maxInputChars: number;
+    readonly maxOutputTokens: number;
+    /** Per-call result sizing target. This does not reduce the Provider generation allowance. */
+    readonly resultCapacityTargetTokens: number;
+}
+export interface MemoryUsage {
+    readonly llmCalls: number;
+    readonly embeddingCalls: number;
+    readonly inputChars: number;
+    readonly reservedOutputTokens: number;
+    readonly reportedInputTokens: number;
+    readonly reportedOutputTokens: number;
+    readonly unreportedCalls: number;
+    readonly unsettledCalls: number;
+}
+export interface EmbeddingResult {
+    readonly vectors: readonly (readonly number[])[];
+    readonly inputTokens?: number;
+}
+/** Trusted callbacks: preserve the result-capacity target and disable hidden retries. */
+export interface MemoryProviders {
+    readonly budget: MemoryBudget;
+    readonly complete: (messages: readonly Message[], resultCapacityTargetTokens: number, signal: AbortSignal) => Promise<ModelTurn>;
+    readonly embed: (texts: readonly string[], signal: AbortSignal) => Promise<EmbeddingResult>;
+}
+/** Use the real Run-injected runner. Background ingestion must not fabricate a Run. */
+export declare function runModel(runner: ModelTaskRunner): MemoryProviders["complete"];
+export declare function providerLimits(providers: MemoryProviders): Record<string, number>;
+export declare function currentExecution(journal?: Journal): ProviderExecution | undefined;
+export declare class ProviderExecution {
+    readonly providers: MemoryProviders;
+    readonly journal: Journal;
+    readonly dimensions: number;
+    readonly maxResults: number;
+    readonly maxInput: number;
+    readonly controller: AbortController;
+    readonly deadline: number;
+    operation: string | undefined;
+    error: string | undefined;
+    constructor(providers: MemoryProviders, journal: Journal, dimensions: number, timeoutMs: number, maxResults: number, maxInput: number);
+    stop(code: string): void;
+    check(): void;
+    run<T>(work: () => Promise<T>): Promise<T>;
+    invoke(kind: "llm", values: readonly Message[], extraction?: boolean): Promise<string>;
+    invoke(kind: "embedding", values: readonly string[]): Promise<number[][]>;
+}
+/** Host owns the SDK handle and its storage resources. */
+export declare class ManagedMem0Client implements Mem0Client {
+    readonly sdk: Mem0Client;
+    readonly dimensions: number;
+    constructor(sdk: Mem0Client, dimensions: number);
+    add(...args: Parameters<Mem0Client["add"]>): Promise<unknown>;
+    get(...args: Parameters<Mem0Client["get"]>): Promise<unknown>;
+    getAll(...args: Parameters<Mem0Client["getAll"]>): Promise<unknown>;
+    search(...args: Parameters<Mem0Client["search"]>): Promise<unknown>;
+    update(...args: Parameters<Mem0Client["update"]>): Promise<unknown>;
+    delete(...args: Parameters<Mem0Client["delete"]>): Promise<unknown>;
+    history(...args: Parameters<Mem0Client["history"]>): Promise<unknown>;
+}
+export interface ManagedMem0Config {
+    readonly vectorStore: {
+        readonly provider: string;
+        readonly config: Record<string, unknown>;
+    };
+    readonly historyDbPath: string;
+    readonly customInstructions?: string;
+}
+/** Only storage/history/instructions are accepted; no unmetered reranker or graph provider. */
+export declare function createManagedClient(options: {
+    config: ManagedMem0Config;
+    embeddingDims: number;
+}): Promise<ManagedMem0Client>;

package/dist/providers.js

@@ -0,0 +1,202 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { Journal, MemoryError } from "./journal.js";
+/** Use the real Run-injected runner. Background ingestion must not fabricate a Run. */
+export function runModel(runner) {
+    return async (messages, resultCapacityTargetTokens, signal) => (await runner.complete(messages, {
+        resultCapacityTargetTokens,
+        resultCapacitySource: "workflow_policy",
+        signal,
+    })).turn;
+}
+export function providerLimits(providers) {
+    if (typeof providers?.complete !== "function" || typeof providers?.embed !== "function")
+        throw new TypeError("invalid memory providers");
+    const b = providers.budget;
+    if (typeof b?.key !== "string" || !b.key.trim() || [...b.key].length > 512)
+        throw new TypeError("invalid budget key");
+    const limits = { max_llm_calls: b.maxLlmCalls, max_embedding_calls: b.maxEmbeddingCalls,
+        max_input_chars: b.maxInputChars, max_output_tokens: b.maxOutputTokens,
+        result_capacity_target_tokens: b.resultCapacityTargetTokens };
+    for (const [name, value] of Object.entries(limits)) {
+        if (!Number.isSafeInteger(value) || value < (name === "result_capacity_target_tokens" ? 1 : 0) || value > 2 ** 31 - 1)
+            throw new TypeError(`invalid ${name}`);
+    }
+    return limits;
+}
+const current = new AsyncLocalStorage();
+export function currentExecution(journal) {
+    const value = current.getStore();
+    return journal === undefined || value?.journal === journal ? value : undefined;
+}
+function execution() {
+    const value = currentExecution();
+    if (!value)
+        throw new MemoryError("memory_provider_unbound");
+    return value;
+}
+export class ProviderExecution {
+    providers;
+    journal;
+    dimensions;
+    maxResults;
+    maxInput;
+    controller = new AbortController();
+    deadline;
+    operation;
+    error;
+    constructor(providers, journal, dimensions, timeoutMs, maxResults, maxInput) {
+        this.providers = providers;
+        this.journal = journal;
+        this.dimensions = dimensions;
+        this.maxResults = maxResults;
+        this.maxInput = maxInput;
+        this.deadline = performance.now() + timeoutMs;
+    }
+    stop(code) {
+        if (!this.error) {
+            this.error = code;
+            if (this.operation)
+                this.journal.providerError(this.operation, code);
+        }
+        this.controller.abort(new MemoryError(this.error));
+    }
+    check() {
+        if (performance.now() >= this.deadline)
+            this.stop("memory_timeout");
+        if (this.error)
+            throw new MemoryError(this.error);
+    }
+    run(work) {
+        return current.run(this, async () => {
+            try {
+                this.check();
+                const result = await work();
+                this.check(); // SDK fallback must not convert a swallowed denial to success.
+                return result;
+            }
+            catch (error) {
+                if (this.error)
+                    throw new MemoryError(this.error);
+                throw error;
+            }
+        });
+    }
+    async invoke(kind, values, extraction = true) {
+        this.check();
+        const resultTarget = kind === "llm" ? this.providers.budget.resultCapacityTargetTokens : 0;
+        const chars = values.reduce((sum, value) => sum + [...(typeof value === "string" ? value : value.content)].length, 0);
+        let id;
+        try {
+            id = this.journal.admit(this.providers.budget.key, this.operation, kind, chars, resultTarget);
+        }
+        catch (error) {
+            this.stop(error instanceof MemoryError ? error.code : "memory_provider_error");
+            throw new MemoryError(this.error);
+        }
+        let inputTokens = null;
+        let generationTokens = null;
+        try {
+            this.check();
+            let content;
+            if (kind === "llm") {
+                const result = await this.providers.complete(values, resultTarget, this.controller.signal);
+                if (result?.usage) {
+                    if (!validTokens(result.usage.inputTokens) || (result.usage.generationTokens !== undefined && !validTokens(result.usage.generationTokens))) {
+                        throw new MemoryError("memory_provider_contract");
+                    }
+                    inputTokens = result.usage.inputTokens;
+                    generationTokens = result.usage.generationTokens ?? null;
+                }
+                const appliedGenerationLimit = result?.appliedGenerationLimit;
+                if (!Number.isSafeInteger(appliedGenerationLimit) || appliedGenerationLimit < resultTarget
+                    || result.finishReason !== "stop" || result.message?.role !== "assistant"
+                    || result.message.toolCalls?.length || typeof result.message.content !== "string"
+                    || (generationTokens !== null && generationTokens > appliedGenerationLimit)) {
+                    throw new MemoryError("memory_provider_contract");
+                }
+                content = result.message.content;
+                if (extraction) {
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(content);
+                    }
+                    catch {
+                        throw new MemoryError("memory_invalid_extraction");
+                    }
+                    if (!parsed || !Array.isArray(parsed.memory) || parsed.memory.length > this.maxResults)
+                        throw new MemoryError("memory_invalid_extraction");
+                    for (const item of parsed.memory) {
+                        if (!item || typeof item.text !== "string" || !item.text.trim() || [...item.text].length > this.maxInput
+                            || (item.entities !== undefined && (!Array.isArray(item.entities) || item.entities.some(e => typeof e !== "string")))) {
+                            throw new MemoryError("memory_invalid_extraction");
+                        }
+                    }
+                }
+            }
+            else {
+                const result = await this.providers.embed(values, this.controller.signal);
+                if (result?.inputTokens !== undefined && !validTokens(result.inputTokens))
+                    throw new MemoryError("memory_provider_contract");
+                inputTokens = result.inputTokens ?? null;
+                generationTokens = 0;
+                if (!Array.isArray(result.vectors) || result.vectors.length !== values.length || result.vectors.some(v => !Array.isArray(v) || v.length !== this.dimensions || v.some(x => typeof x !== "number" || !Number.isFinite(x)))) {
+                    throw new MemoryError("memory_provider_contract");
+                }
+                content = result.vectors.map(v => [...v]);
+            }
+            this.check();
+            this.journal.settle(id, "complete", inputTokens, generationTokens);
+            return content;
+        }
+        catch (error) {
+            this.journal.settle(id, "failed", inputTokens, generationTokens);
+            this.stop(error instanceof MemoryError ? error.code : "memory_provider_error");
+            throw new MemoryError(this.error);
+        }
+    }
+}
+function validTokens(value) { return Number.isSafeInteger(value) && value >= 0 && value <= 2 ** 31 - 1; }
+/** Host owns the SDK handle and its storage resources. */
+export class ManagedMem0Client {
+    sdk;
+    dimensions;
+    constructor(sdk, dimensions) {
+        this.sdk = sdk;
+        this.dimensions = dimensions;
+    }
+    add(...args) { return this.sdk.add(...args); }
+    get(...args) { return this.sdk.get(...args); }
+    getAll(...args) { return this.sdk.getAll(...args); }
+    search(...args) { return this.sdk.search(...args); }
+    update(...args) { return this.sdk.update(...args); }
+    delete(...args) { return this.sdk.delete(...args); }
+    history(...args) { return this.sdk.history(...args); }
+}
+/** Only storage/history/instructions are accepted; no unmetered reranker or graph provider. */
+export async function createManagedClient(options) {
+    const { config, embeddingDims } = options;
+    if (!Number.isSafeInteger(embeddingDims) || embeddingDims < 1 || embeddingDims > 65_536)
+        throw new TypeError("invalid embeddingDims");
+    if (!config || Object.keys(config).some(k => !["vectorStore", "historyDbPath", "customInstructions"].includes(k)))
+        throw new TypeError("managed config accepts only storage/history/instructions");
+    if (!config.vectorStore || typeof config.historyDbPath !== "string" || !config.historyDbPath.trim())
+        throw new TypeError("explicit vectorStore and historyDbPath are required");
+    const { Memory } = await import("mem0ai/oss");
+    const sdk = new Memory({ ...config,
+        llm: { provider: "langchain", config: { model: { async invoke(messages) {
+                        const roles = { human: "user", ai: "assistant", system: "system" };
+                        const converted = messages.map(message => {
+                            const role = roles[(message.type ?? message.getType?.())];
+                            if (!role || typeof message.content !== "string")
+                                throw new MemoryError("memory_provider_contract");
+                            return { role, content: message.content };
+                        });
+                        return { content: await execution().invoke("llm", converted) };
+                    } } } },
+        embedder: { provider: "langchain", config: { embeddingDims, model: {
+                    async embedQuery(text) { return (await execution().invoke("embedding", [text]))[0]; },
+                    async embedDocuments(texts) { return execution().invoke("embedding", texts); },
+                } } },
+    });
+    return new ManagedMem0Client(sdk, embeddingDims);
+}

package/dist/workflow.d.ts

@@ -0,0 +1,18 @@
+import { Mem0Memory } from "./memory.js";
+import type { MemoryOperation, MemoryRecord, MemoryResolution, MemoryReview } from "./memory.js";
+export type MemoryDecisionPolicy = (candidate: MemoryRecord, review: MemoryReview) => Promise<MemoryResolution | undefined> | MemoryResolution | undefined;
+export interface MemoryWorkflowResult {
+    readonly extraction: MemoryOperation;
+    readonly resolutions: readonly MemoryOperation[];
+    readonly pendingIds: readonly string[];
+}
+/** Reuse the journal on retry; authorization remains an explicit host policy. */
+export declare class MemoryWorkflow {
+    #private;
+    constructor(memory: Mem0Memory, options?: {
+        policy?: MemoryDecisionPolicy;
+        policyRevision?: string;
+        reviewLimit?: number;
+    });
+    capture(messages: Parameters<Mem0Memory["extract"]>[0], options: Parameters<Mem0Memory["extract"]>[1]): Promise<MemoryWorkflowResult>;
+}

package/dist/workflow.js

@@ -0,0 +1,60 @@
+import { createHash } from "node:crypto";
+import { Mem0Memory, requiredText, positiveInteger } from "./memory.js";
+function digest(value) { return createHash("sha256").update(value).digest("hex"); }
+/** Reuse the journal on retry; authorization remains an explicit host policy. */
+export class MemoryWorkflow {
+    #memory;
+    #policy;
+    #revision;
+    #limit;
+    constructor(memory, options = {}) {
+        this.#memory = memory;
+        this.#policy = options.policy;
+        if (this.#policy !== undefined && typeof this.#policy !== "function")
+            throw new TypeError("policy must be callable");
+        this.#revision = requiredText(options.policyRevision ?? "review-only", "policy revision", 512);
+        this.#limit = positiveInteger(options.reviewLimit ?? 8, "review limit", 32);
+    }
+    async capture(messages, options) {
+        const prefix = "workflow:" + digest(requiredText(options.key, "workflow key", 512));
+        const extraction = await this.#memory.extract(messages, { ...options, key: prefix + ":extract" });
+        const resolutions = [];
+        const pendingIds = [];
+        if (extraction.state === "complete")
+            for (const id of extraction.ids) {
+                const suffix = digest(this.#revision + "\0" + id);
+                const resolveKey = prefix + ":resolve:" + suffix;
+                const existing = this.#memory.operation(resolveKey);
+                if (existing) {
+                    resolutions.push(existing);
+                    if (existing.state !== "complete")
+                        pendingIds.push(id);
+                    continue;
+                }
+                const signal = options.signal === undefined ? {} : { signal: options.signal };
+                const record = await this.#memory.get(id, { includeInactive: true, ...signal });
+                if (!record || record.state !== "pending")
+                    continue;
+                const reviewed = await this.#memory.review({ id, version: record.version }, {
+                    key: prefix + ":review:" + suffix, limit: this.#limit, ...signal,
+                });
+                if (reviewed.state !== "complete" || !reviewed.review || !this.#policy) {
+                    pendingIds.push(id);
+                    continue;
+                }
+                const decision = await this.#policy(record, reviewed.review);
+                if (!decision) {
+                    pendingIds.push(id);
+                    continue;
+                }
+                if (decision.reviewKey !== reviewed.review.key || !decision.items.some(ref => ref.id === id && ref.version === record.version)) {
+                    throw new TypeError("Workflow decision must include the candidate and its review key");
+                }
+                const resolved = await this.#memory.resolve(decision, { key: resolveKey, ...signal });
+                resolutions.push(resolved);
+                if (resolved.state !== "complete")
+                    pendingIds.push(id);
+            }
+        return Object.freeze({ extraction, resolutions: Object.freeze(resolutions), pendingIds: Object.freeze(pendingIds) });
+    }
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "purra-mem0",
+  "version": "0.5.0",
+  "description": "Scoped Mem0 OSS memory integration for PurrA",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test test/*.test.mjs",
+    "test:types": "tsc -p test/tsconfig.json",
+    "test:sdk": "tsc -p test/tsconfig.sdk.json && node scripts/check-sdk.mjs",
+    "check": "npm run build && npm test && npm run test:types",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "mem0ai": "3.1.7",
+    "purra": "0.5.0",
+    "@langchain/core": "1.1.47"
+  },
+  "devDependencies": {
+    "@langchain/core": "1.1.47",
+    "@types/node": "22.20.1",
+    "purra": "file:../../../typescript",
+    "typescript": "7.0.2"
+  },
+  "peerDependenciesMeta": {
+    "@langchain/core": {
+      "optional": true
+    }
+  }
+}