purra-mem0 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lybrands
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# purra-mem0 · TypeScript
+
+English | [简体中文](README.zh-CN.md)
+
+Scoped memory, retrieval, and lifecycle management using `Memory` from
+`mem0ai/oss`. Requires Node.js 22.13+; hosted Mem0 Platform clients are not supported.
+
+## Install
+
+Follow [source installation](../../README.md#source-installation), selecting
+`integrations/mem0/typescript`. Mem0's local store needs the `better-sqlite3`
+native installation scripts.
+
+For managed LLM/Embedding callbacks, install the optional peer in your application:
+
+```sh
+npm install @langchain/core@1.1.47
+```
+
+Before importing Mem0, set `MEM0_TELEMETRY=false` and an application-owned
+`MEM0_DIR`. Explicitly configure the LLM, embedder, `vectorStore.config.dbPath`,
+and `historyDbPath`.
+
+## Save and read
+
+The application supplies `mem0Config`, authenticated `userId`, authorized
+`projectId`, and a persistent `journalPath`:
+
+```ts
+import { Memory } from "mem0ai/oss";
+import { Mem0Memory } from "purra-mem0";
+
+const sdk = new Memory(mem0Config);
+const memory = new Mem0Memory({
+  client: sdk,
+  scope: { user: userId, project: projectId },
+  journalPath,
+});
+
+async function savePreference() {
+  const saved = await memory.add("Reply in Chinese.", {
+    source: { id: "preference:language", revision: "1" },
+    key: "preference:language:1",
+  });
+  return memory.get(saved.ids[0]!);
+}
+```
+
+`add` creates an active record by default; use `state: "pending"` for review first.
+`get` returns `undefined` for unavailable records. Updates, state changes, and
+deletions require the current `version` and a stable operation `key`.
+
+## Connect to an Agent
+
+Supply `memoryQuery` as a function that selects query text from a Core `ContextRequest`:
+
+```ts
+import { RetrieverTool } from "purra";
+import { MemoryContext } from "purra-mem0";
+
+const recall = new RetrieverTool({
+  retriever: memory,
+  name: "recallMemory",
+  description: "Recall saved preferences and facts.",
+});
+const context = new MemoryContext({ memory, query: memoryQuery });
+```
+
+Add `recall.definition` to the Agent's tools, or compose `context` with its context
+providers. The memory instance already binds the scope. For explicit record
+selection, use `assembleMemoryContext(memory, ids, allowance)`.
+
+## Managed model calls
+
+Use the following configuration instead of a raw SDK client when calls need
+persistent budgets. Storage paths, embedding dimensions, and the budget key come
+from the application; the numeric limits below illustrate a budget configuration.
+
+`modelTasks` is the runner supplied by a PurrA extension factory.
+The async `embed(texts, signal)` callback must return `EmbeddingResult` with
+vectors and any reported input-token usage.
+
+```ts
+import { createManagedClient, runModel } from "purra-mem0";
+
+const client = await createManagedClient({
+  embeddingDims: embeddingDimensions,
+  config: { vectorStore: vectorStoreConfig, historyDbPath: historyPath },
+});
+const memory = new Mem0Memory({
+  client,
+  scope: { user: userId, project: projectId },
+  journalPath,
+  allowInference: true,
+  providers: {
+    budget: {
+      key: budgetKey,
+      maxLlmCalls: 4,
+      maxEmbeddingCalls: 64,
+      maxInputChars: 100_000,
+      maxOutputTokens: 8192,
+      resultCapacityTargetTokens: 2048,
+    },
+    complete: runModel(modelTasks),
+    embed,
+  },
+});
+```
+
+Use `memory.budgetUsage()` to inspect admitted and reported usage. Raw SDK mode
+reports internal usage as unknown.
+
+`resultCapacityTargetTokens` reserves the expected per-call memory result size.
+It is not the Provider generation limit; `runModel()` preserves the Run's user
+generation ceiling and records the memory value as a workflow capacity target.
+
+## Extract and review
+
+With managed providers and `allowInference: true`:
+
+```ts
+import { MemoryWorkflow, type MemorySource } from "purra-mem0";
+
+const workflow = new MemoryWorkflow(memory);
+
+async function capture(
+  messages: readonly { role: "user" | "assistant"; content: string }[],
+  source: MemorySource,
+  operationKey: string,
+) {
+  return workflow.capture(messages, { source, key: operationKey });
+}
+```
+
+This configuration reviews candidates and leaves them pending. To apply decisions,
+pass `policy(candidate, review)` and a stable `policyRevision` to `MemoryWorkflow`.
+Return an authorized `MemoryResolution` that retains the review key, or `undefined`
+to leave the candidate pending. The policy may be async.
+
+## Lifecycle
+
+Before shutdown, call `await memory.drain()` and `memory.close()`, then close SDK
+and provider resources. For paging, withdrawal, evidence validation, and uncertain
+writes, see the [memory lifecycle guide](../README.md).

package/README.zh-CN.md

@@ -0,0 +1,133 @@
+# purra-mem0 · TypeScript
+
+[English](README.md) | 简体中文
+
+使用 `mem0ai/oss` 的 `Memory` 提供作用域记忆、检索和生命周期管理。
+要求 Node.js 22.13+，不支持托管的 Mem0 Platform 客户端。
+
+## 安装
+
+按照[源码安装说明](../../README.zh-CN.md#从源码安装)操作，选择
+`integrations/mem0/typescript`。Mem0 的本地存储需要执行 `better-sqlite3` 的原生安装脚本。
+
+需要受控的 LLM/Embedding 回调时，在应用中安装可选 peer 依赖：
+
+```sh
+npm install @langchain/core@1.1.47
+```
+
+导入 Mem0 前，设置 `MEM0_TELEMETRY=false`，并将 `MEM0_DIR` 指向应用管理的数据目录。
+显式配置 LLM、embedder、`vectorStore.config.dbPath` 和 `historyDbPath`。
+
+## 保存与读取
+
+应用提供 `mem0Config`、已认证的 `userId`、已授权的 `projectId`，以及持久化 `journalPath`：
+
+```ts
+import { Memory } from "mem0ai/oss";
+import { Mem0Memory } from "purra-mem0";
+
+const sdk = new Memory(mem0Config);
+const memory = new Mem0Memory({
+  client: sdk,
+  scope: { user: userId, project: projectId },
+  journalPath,
+});
+
+async function savePreference() {
+  const saved = await memory.add("Reply in Chinese.", {
+    source: { id: "preference:language", revision: "1" },
+    key: "preference:language:1",
+  });
+  return memory.get(saved.ids[0]!);
+}
+```
+
+`add` 默认创建已启用记录；需要先审核时设置 `state: "pending"`。
+记录不可用时，`get` 返回 `undefined`。更新、状态切换和删除需要当前 `version` 与稳定的操作 `key`。
+
+## 接入 Agent
+
+提供 `memoryQuery` 函数，从 Core 的 `ContextRequest` 中选取查询文本：
+
+```ts
+import { RetrieverTool } from "purra";
+import { MemoryContext } from "purra-mem0";
+
+const recall = new RetrieverTool({
+  retriever: memory,
+  name: "recallMemory",
+  description: "Recall saved preferences and facts.",
+});
+const context = new MemoryContext({ memory, query: memoryQuery });
+```
+
+将 `recall.definition` 加入 Agent 工具，或将 `context` 与其他上下文提供器组合。
+记忆实例已经绑定作用域。需要显式选择记录时，使用 `assembleMemoryContext(memory, ids, allowance)`。
+
+## 受控模型调用
+
+调用需要持久化预算时，使用以下配置替代原生 SDK 客户端。
+存储路径、向量维度和预算键由应用提供，数值仅用于演示预算配置。
+
+`modelTasks` 是 PurrA 扩展工厂提供的执行器。
+异步回调 `embed(texts, signal)` 需要返回 `EmbeddingResult`，包含向量和服务报告的输入 Token 用量。
+
+```ts
+import { createManagedClient, runModel } from "purra-mem0";
+
+const client = await createManagedClient({
+  embeddingDims: embeddingDimensions,
+  config: { vectorStore: vectorStoreConfig, historyDbPath: historyPath },
+});
+const memory = new Mem0Memory({
+  client,
+  scope: { user: userId, project: projectId },
+  journalPath,
+  allowInference: true,
+  providers: {
+    budget: {
+      key: budgetKey,
+      maxLlmCalls: 4,
+      maxEmbeddingCalls: 64,
+      maxInputChars: 100_000,
+      maxOutputTokens: 8192,
+      resultCapacityTargetTokens: 2048,
+    },
+    complete: runModel(modelTasks),
+    embed,
+  },
+});
+```
+
+通过 `memory.budgetUsage()` 查看已准入调用和报告用量。原生 SDK 模式的内部用量记为未知。
+
+`resultCapacityTargetTokens` 用于预留单次记忆结果的预期容量，并不是 Provider 生成上限。
+`runModel()` 会保留 Run 的用户生成上限，并把该值记录为工作流容量目标。
+
+## 提取与审查
+
+配置受控模型调用并设置 `allowInference: true` 后：
+
+```ts
+import { MemoryWorkflow, type MemorySource } from "purra-mem0";
+
+const workflow = new MemoryWorkflow(memory);
+
+async function capture(
+  messages: readonly { role: "user" | "assistant"; content: string }[],
+  source: MemorySource,
+  operationKey: string,
+) {
+  return workflow.capture(messages, { source, key: operationKey });
+}
+```
+
+此配置审查候选并让其保持待处理。需要应用决定时，为 `MemoryWorkflow` 传入
+`policy(candidate, review)` 和稳定的 `policyRevision`。
+策略返回已授权且保留审查键的 `MemoryResolution`，或返回 `undefined` 保持待处理；策略可以是异步函数。
+
+## 生命周期
+
+关闭前调用 `await memory.drain()` 和 `memory.close()`，再关闭 SDK 与模型服务资源。
+分页、来源撤回、证据校验和不确定写入的处理见[记忆生命周期指南](../README.zh-CN.md)。

package/dist/context.d.ts

@@ -0,0 +1,29 @@
+import type { ContextBlock, ContextEvidenceReceipt, ContextBudget, ContextBudgetClaim, ContextBundle, ContextProvider, ContextRequest } from "purra";
+import { Mem0Memory } from "./memory.js";
+export declare class MemoryContext implements ContextProvider {
+    #private;
+    constructor(options: {
+        memory: Mem0Memory;
+        query: (request: ContextRequest) => string;
+        countTokens?: (content: string) => number;
+        name?: string;
+        desiredTokens?: number;
+        limit?: number;
+    });
+    describeContextDemands(): readonly ContextBudgetClaim[];
+    buildContext(request: ContextRequest, budget: ContextBudget, signal?: AbortSignal): Promise<ContextBundle>;
+}
+export interface MemoryContextResult {
+    readonly block?: ContextBlock;
+    readonly included: readonly string[];
+    readonly deferred: readonly string[];
+    readonly missing: readonly string[];
+    readonly receipts: readonly ContextEvidenceReceipt[];
+}
+/** Fresh authorized records; shared by Agent and non-Run consumers. */
+export declare function assembleMemoryContext(memory: Mem0Memory, ids: readonly string[], allowance: number, options?: {
+    name?: string;
+    countTokens?: (content: string) => number;
+    expectedEpoch?: number;
+    signal?: AbortSignal;
+}): Promise<MemoryContextResult>;

package/dist/context.js

@@ -0,0 +1,69 @@
+import { estimateJsonTokens } from "purra";
+import { Mem0Memory, positiveInteger, requiredText } from "./memory.js";
+export class MemoryContext {
+    #memory;
+    #query;
+    #countTokens;
+    #name;
+    #desiredTokens;
+    #limit;
+    constructor(options) {
+        this.#memory = options.memory;
+        this.#query = options.query;
+        this.#countTokens = options.countTokens ?? estimateJsonTokens;
+        this.#name = requiredText(options.name ?? "memory", "context name", 128);
+        this.#desiredTokens = positiveInteger(options.desiredTokens ?? 1024, "desiredTokens", 1_000_000);
+        this.#limit = positiveInteger(options.limit ?? 8, "limit");
+        if (typeof this.#query !== "function" || typeof this.#countTokens !== "function")
+            throw new TypeError("query and countTokens must be host functions");
+    }
+    describeContextDemands() {
+        return [{ name: this.#name, desiredTokens: this.#desiredTokens }];
+    }
+    async buildContext(request, budget, signal) {
+        const allowance = budget.contextAllocations[this.#name] ?? 0;
+        if (!allowance)
+            return { blocks: [] };
+        const epoch = this.#memory.epoch;
+        const hits = await this.#memory.retrieve({ query: this.#query(request), limit: this.#limit, scope: {} }, signal);
+        const result = await assembleMemoryContext(this.#memory, hits.map(hit => hit.id), allowance, { name: this.#name, countTokens: this.#countTokens, expectedEpoch: epoch, ...(signal ? { signal } : {}) });
+        return { blocks: result.block ? [result.block] : [] };
+    }
+}
+/** Fresh authorized records; shared by Agent and non-Run consumers. */
+export async function assembleMemoryContext(memory, ids, allowance, options = {}) {
+    if (!Number.isSafeInteger(allowance) || allowance < 0 || allowance > 1_000_000)
+        throw new TypeError("invalid context allowance");
+    const name = requiredText(options.name ?? "memory", "context name", 128);
+    const countTokens = options.countTokens ?? estimateJsonTokens;
+    const epoch = options.expectedEpoch ?? memory.epoch;
+    memory.assertEpoch(epoch);
+    const hits = await memory.select(ids, options.signal ? { signal: options.signal } : {});
+    const selected = [], deferred = [], rows = [];
+    let content = "", tokenCount = 0;
+    for (const hit of hits) {
+        const row = { id: hit.id, version: hit.version, text: hit.content, sourceId: hit.metadata.sourceId,
+            sourceRevision: hit.metadata.sourceRevision, metadata: hit.metadata.metadata };
+        const candidate = JSON.stringify([...rows, row]);
+        let count = countTokens(candidate);
+        if (!Number.isSafeInteger(count) || count < 0)
+            throw new TypeError("countTokens must return a non-negative integer");
+        count = Math.max(count, estimateJsonTokens(candidate));
+        if (count <= allowance) {
+            rows.push(row);
+            selected.push(hit);
+            content = candidate;
+            tokenCount = count;
+        }
+        else
+            deferred.push(hit.id);
+    }
+    const receipts = Object.freeze(selected.map(hit => Object.freeze({ evidenceId: hit.metadata.evidenceId,
+        contextBlock: name, source: hit.source, itemId: hit.id, version: String(hit.version) })));
+    await memory.validateEvidence(receipts, options.signal ? { signal: options.signal } : {});
+    memory.assertEpoch(epoch);
+    const found = new Set(hits.map(hit => hit.id));
+    return Object.freeze({ ...(selected.length ? { block: { name, content, tokenCount, untrusted: true, evidence: receipts } } : {}),
+        included: Object.freeze(selected.map(hit => hit.id)), deferred: Object.freeze(deferred),
+        missing: Object.freeze([...new Set(ids.filter(id => !found.has(id)))]), receipts });
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/** Optional Node.js integration; not imported by PurrA Core. */
+export { MemoryError } from "./journal.js";
+export { Mem0Memory } from "./memory.js";
+export type { Mem0Client, MemoryScope, MemorySource, MemoryRecord, MemoryMetadata, MemoryFilters, MemoryPage, MemoryOperation, MemoryRef, MemoryLink, MemoryLinkPage, MemoryResolution, MemoryReview, MemoryMatch } from "./memory.js";
+export type { MemoryContextResult } from "./context.js";
+export { MemoryContext, assembleMemoryContext } from "./context.js";
+export { createManagedClient, runModel } from "./providers.js";
+export type { MemoryBudget, MemoryProviders, MemoryUsage, EmbeddingResult, ManagedMem0Config } from "./providers.js";
+export { MemoryWorkflow } from "./workflow.js";
+export type { MemoryWorkflowResult, MemoryDecisionPolicy } from "./workflow.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+/** Optional Node.js integration; not imported by PurrA Core. */
+export { MemoryError } from "./journal.js";
+export { Mem0Memory } from "./memory.js";
+export { MemoryContext, assembleMemoryContext } from "./context.js";
+export { createManagedClient, runModel } from "./providers.js";
+export { MemoryWorkflow } from "./workflow.js";

package/dist/journal.d.ts

@@ -0,0 +1,101 @@
+import type { MemoryUsage } from "./providers.js";
+import type { MemoryMetadata, MemoryResolution, MemoryRef, MemoryReview, MemoryLink } from "./memory.js";
+export declare class MemoryError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+export interface Metadata {
+    purra_scope: string;
+    purra_store: string;
+    purra_operation: string;
+    purra_version: number;
+    purra_state: "active" | "pending" | "disabled";
+    purra_source: string;
+    purra_revision: string;
+    purra_inferred: boolean;
+    purra_expires: string | null;
+    purra_metadata: MemoryMetadata;
+    purra_reason: string | null;
+    purra_created: string;
+    purra_updated: string;
+}
+export interface ItemView {
+    version: number;
+    state: Metadata["purra_state"];
+    metadata: MemoryMetadata;
+    reason: string | null;
+    createdAt: string;
+    updatedAt: string;
+    resolution?: string | null;
+}
+export interface Item {
+    id: string;
+    meta: Metadata;
+    hash: string;
+    deleted: boolean;
+    view?: ItemView;
+}
+export declare function itemView(row: Item): ItemView;
+export interface Plan {
+    kind: string;
+    target: string | null;
+    meta: Metadata | null;
+    hash?: string | null;
+    discarding?: boolean;
+    budget?: string;
+    provider_error?: string;
+    providers_verified?: boolean;
+    resolution?: MemoryResolution;
+    review_key?: string;
+    review_epoch?: number;
+    review_refs?: readonly MemoryRef[];
+    review?: Omit<MemoryReview, "proposal" | "key">;
+    policy_hash?: string;
+    changes?: Partial<ItemView>;
+    link?: Omit<MemoryLink, "key" | "valid">;
+}
+export interface OperationRow {
+    key: string;
+    fingerprint: string;
+    state: "running" | "unknown" | "failed" | "complete" | "discarded";
+    plan: Plan;
+    ids: string[] | null;
+}
+/** Only control metadata is stored here. Content and vectors remain in Mem0. */
+export declare class Journal {
+    private readonly scope;
+    private readonly db;
+    readonly store: string;
+    constructor(path: string, scope: string);
+    private transaction;
+    operation(key: string): OperationRow | undefined;
+    begin(key: string, fingerprint: string, plan: Plan): OperationRow | undefined;
+    savePlan(key: string, plan: Plan): void;
+    saveIds(key: string, ids: string[]): void;
+    budget(key: string, limits: Record<string, number>): void;
+    usage(column: "budget" | "operation", key: string): MemoryUsage;
+    admit(budget: string, operation: string | undefined, kind: "llm" | "embedding", chars: number, reserve: number): string;
+    settle(id: string, state: string, inputTokens?: number | null, generationTokens?: number | null): void;
+    providerError(key: string, code: string): void;
+    verifyProviders(key: string): void;
+    fail(key: string, dispatched: boolean): void;
+    discard(key: string): void;
+    revoked(source: string, revision: string): boolean;
+    assertSource(meta: Pick<Metadata, "purra_source" | "purra_revision">): void;
+    revokeSource(key: string, fingerprint: string, source: string, revision: string | null): void;
+    item(id: string): Item | undefined;
+    resolve(key: string, fingerprint: string, plan: Plan, epoch: number): void;
+    control(key: string, fingerprint: string, plan: Plan, epoch: number, refs: readonly MemoryRef[], changes: readonly Partial<ItemView>[]): void;
+    assertSnapshot(plan: Plan): void;
+    links(id: string, after: string | undefined, limit: number): {
+        key: string;
+        data: NonNullable<Plan["link"]>;
+    }[];
+    reviewPlan(key: string): Plan;
+    finishReview(key: string, plan: Plan): void;
+    items(state: string | null, after: string | undefined, limit: number): Item[];
+    writing(id: string): boolean;
+    commit(key: string, records: Item[]): void;
+    get epoch(): number;
+    close(): void;
+}