purra-mem0 1.0.0 → 1.0.4

package/README.md

@@ -133,6 +133,41 @@ pass `policy(candidate, review)` and a stable `policyRevision` to `MemoryWorkflo
 Return an authorized `MemoryResolution` that retains the review key, or `undefined`
 to leave the candidate pending. The policy may be async.
 
+To require authorization before messages can reach Mem0 or its providers, bind a
+host-issued grant to the exact capture intent:
+
+```ts
+import { MemoryWorkflow, memoryCaptureIntent } from "purra-mem0";
+
+const capturePolicyId = "project-memory";
+const capturePolicyRevision = "2026-09-09";
+const authorization = {
+  intentDigest: memoryCaptureIntent(messages, { source, metadata }),
+  policyId: capturePolicyId,
+  policyRevision: capturePolicyRevision,
+  principalId: authenticatedUserId,
+  decisionId: hostDecisionId,
+};
+const workflow = new MemoryWorkflow(memory, { capturePolicyId, capturePolicyRevision });
+await memory.recordCaptureAuthorization(authorization, {
+  key: `capture-authorization:${hostDecisionId}`,
+  expiresAt: captureAuthorizationExpiresAt,
+});
+const result = await workflow.capture(messages, {
+  source, key: operationKey, metadata, authorization,
+});
+```
+
+The host owns authentication, eligibility and audit of the decision. Keep the
+authorization unchanged on retry. Missing or mismatched grants fail before the
+operation journal and Provider calls; changing a bound grant under the same key
+causes an idempotency conflict.
+
+Call `revokeCaptureAuthorization(policyId, decisionId, { key })` to persist a
+revocation. It prevents new extraction, review and activation under the decision
+and hides records produced by it. Expiry only stops new processing. Neither path
+physically deletes Mem0 content or history.
+
 ## Lifecycle
 
 Before shutdown, call `await memory.drain()` and `memory.close()`, then close SDK
@@ -143,3 +178,19 @@ writes, see the [memory lifecycle guide](../README.md).
 ## Native managed providers
 
 `createManagedClient` inject native LLM and Embedding adapters into a version-pinned, package-private Mem0 module. Calls retain the existing PurrA budget, cancellation and result validation. Explicit vector dimensions must agree; the managed path rejects LangChain vector stores. It neither patches the installed SDK nor starts a proxy server. See [third-party notices](THIRD_PARTY_NOTICES.md). Raw SDK clients remain host-owned and do not acquire managed accounting automatically.
+
+## Host-controlled selection and relation proposals
+
+`new MemoryContext({ memory, selectIds: hostSelect })` accepts an async
+`hostSelect(request, signal)` returning ordered memory IDs. Supply either
+`selectIds` or the existing `query`, never both. The component rereads authorized
+records, validates evidence, and fits complete records into the context budget.
+The host owns retrieval combination, ordering, callback timeout and model costs.
+
+`proposeMemoryRelations(memory, refs, { relations: allowedNames, extract: hostExtract })`
+is exported from `purra-mem0`. Its async extractor receives `(input, signal)` and
+returns objects with exactly `from`, `to`, `relation`, `fromQuote`, `toQuote` string
+fields. IDs must match supplied `MemoryRef` revisions and quotes must occur in
+those records. Returned immutable proposals do not write links or prove that a
+relation is true. The host reviews proposals and explicitly calls `memory.link`.
+No automatic model invocation, retry or adoption policy is installed.

package/README.zh-CN.md

@@ -123,6 +123,34 @@ async function capture(
 `policy(candidate, review)` 和稳定的 `policyRevision`。
 策略返回已授权且保留审查键的 `MemoryResolution`，或返回 `undefined` 保持待处理；策略可以是异步函数。
 
+需要在消息到达 Mem0 或 Provider 前强制授权时，绑定宿主签发的准确捕获意图：
+
+```ts
+import { MemoryWorkflow, memoryCaptureIntent } from "purra-mem0";
+
+const authorization = {
+  intentDigest: memoryCaptureIntent(messages, { source, metadata }),
+  policyId: capturePolicyId,
+  policyRevision: capturePolicyRevision,
+  principalId: authenticatedUserId,
+  decisionId: hostDecisionId,
+};
+const workflow = new MemoryWorkflow(memory, { capturePolicyId, capturePolicyRevision });
+await memory.recordCaptureAuthorization(authorization, {
+  key: `capture-authorization:${hostDecisionId}`,
+  expiresAt: captureAuthorizationExpiresAt,
+});
+const result = await workflow.capture(messages, {
+  source, key: operationKey, metadata, authorization,
+});
+```
+
+宿主负责认证、内容适用性和决定审计。重试必须沿用相同授权；缺失或不匹配的授权会在
+操作日志及 Provider 调用前失败，同一 key 更换已绑定授权会触发幂等冲突。
+调用 `revokeCaptureAuthorization(policyId, decisionId, { key })` 可持久撤销决定，阻止
+新的提取、审查和激活，并隐藏由其产生的记录。到期只阻止新处理；两者均不物理删除
+Mem0 内容或历史。
+
 ## 生命周期
 
 关闭前调用 `await memory.drain()` 和 `memory.close()`，再关闭 SDK 与模型服务资源。
@@ -132,3 +160,14 @@ async function capture(
 ## 原生受控适配
 
 `createManagedClient` 把 PurrA 的原生模型和向量适配器注入包内、版本固定的 Mem0 私有模块，沿用现有预算、取消与结果校验。向量维度必须一致，受控路径拒绝 LangChain 向量库。不修改宿主安装的官方 SDK，也不启动代理服务。来源、许可证与修改说明见[第三方声明](THIRD_PARTY_NOTICES.md)。直接传入的原始 SDK 客户端仍由宿主管理，不自动获得受控回调的计费。
+
+## 宿主选择与关系候选
+
+`MemoryContext` 支持异步 `selectIds(request, signal)`，与原有 `query` 二选一。
+宿主返回有序记忆 ID；组件重新读取并验证来源、版本和预算，不接受替换文本。
+
+`purra-mem0` 导出的 `proposeMemoryRelations` 接受记忆引用、宿主关系词表和异步 `extract`。
+抽取回调返回仅含 `from`、`to`、`relation`、`fromQuote`、`toQuote` 字符串的对象数组。
+组件校验原文引用与当前记忆版本，只返回候选，不自动写入关系。
+关系是否成立、是否采纳和显式调用 `memory.link` 均由宿主决定。
+模型调用的授权、超时和费用预算也由宿主负责。

package/dist/context.d.ts

@@ -1,10 +1,12 @@
 import type { ContextBlock, ContextEvidenceReceipt, ContextBudget, ContextBudgetClaim, ContextBundle, ContextProvider, ContextRequest } from "purra";
 import { Mem0Memory } from "./memory.js";
+export type MemorySelectionPolicy = (request: ContextRequest, signal?: AbortSignal) => Promise<readonly string[]>;
 export declare class MemoryContext implements ContextProvider {
     #private;
     constructor(options: {
         memory: Mem0Memory;
-        query: (request: ContextRequest) => string;
+        query?: (request: ContextRequest) => string;
+        selectIds?: MemorySelectionPolicy;
         countTokens?: (content: string) => number;
         name?: string;
         desiredTokens?: number;

package/dist/context.js

@@ -1,8 +1,14 @@
 import { estimateJsonTokens } from "purra";
 import { Mem0Memory, positiveInteger, requiredText } from "./memory.js";
+import { MemoryError } from "./journal.js";
+function validateContextAllowance(value) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0 || value > 1_000_000)
+        throw new TypeError("invalid context allowance");
+}
 export class MemoryContext {
     #memory;
     #query;
+    #selectIds;
     #countTokens;
     #name;
     #desiredTokens;
@@ -10,32 +16,44 @@ export class MemoryContext {
     constructor(options) {
         this.#memory = options.memory;
         this.#query = options.query;
+        this.#selectIds = options.selectIds;
         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");
+        if ((this.#query === undefined) === (this.#selectIds === undefined))
+            throw new TypeError("Provide exactly one of query or selectIds");
+        if (typeof (this.#selectIds ?? this.#query) !== "function" || typeof this.#countTokens !== "function")
+            throw new TypeError("Selection 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)
+        const allowance = Object.hasOwn(budget.contextAllocations, this.#name) ? budget.contextAllocations[this.#name] : 0;
+        validateContextAllowance(allowance);
+        if (allowance === 0)
             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 } : {}) });
+        if (signal?.aborted)
+            throw new MemoryError("memory_cancelled");
+        const ids = this.#selectIds === undefined
+            ? (await this.#memory.retrieve({ query: this.#query(request), limit: this.#limit, scope: {} }, signal)).map(hit => hit.id)
+            : await this.#selectIds(request, signal);
+        const result = await assembleMemoryContext(this.#memory, ids, 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");
+    validateContextAllowance(allowance);
+    const countTokens = options.countTokens === undefined ? estimateJsonTokens : options.countTokens;
+    if (typeof countTokens !== "function")
+        throw new TypeError("countTokens must be callable");
     const name = requiredText(options.name ?? "memory", "context name", 128);
-    const countTokens = options.countTokens ?? estimateJsonTokens;
+    if (!Array.isArray(ids))
+        throw new TypeError("ids must be an array");
+    ids = Object.freeze([...ids]);
     const epoch = options.expectedEpoch ?? memory.epoch;
     memory.assertEpoch(epoch);
     const hits = await memory.select(ids, options.signal ? { signal: options.signal } : {});

package/dist/index.d.ts

@@ -1,10 +1,12 @@
 /** 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 { Mem0Memory, memoryCaptureIntent } from "./memory.js";
+export type { Mem0Client, MemoryScope, MemorySource, MemoryCaptureAuthorization, MemoryRecord, MemoryMetadata, MemoryFilters, MemoryPage, MemoryOperation, MemoryRef, MemoryLink, MemoryLinkPage, MemoryRelationEvidence, MemoryResolution, MemoryReview, MemoryMatch } from "./memory.js";
+export type { MemoryContextResult, MemorySelectionPolicy } 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";
+export { proposeMemoryRelations } from './relations.js';
+export type { MemoryRelationProposal, MemoryRelationExtractionInput, MemoryRelationExtractor } from './relations.js';

package/dist/index.js

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

package/dist/journal.d.ts

@@ -18,6 +18,8 @@ export interface Metadata {
     purra_reason: string | null;
     purra_created: string;
     purra_updated: string;
+    purra_capture_policy?: string;
+    purra_capture_decision?: string;
 }
 export interface ItemView {
     version: number;
@@ -53,6 +55,17 @@ export interface Plan {
     policy_hash?: string;
     changes?: Partial<ItemView>;
     link?: Omit<MemoryLink, "key" | "valid">;
+    capture_authorization?: {
+        intent_digest: string;
+        policy_id: string;
+        policy_revision: string;
+        principal_id: string;
+        decision_id: string;
+    };
+    valid_from?: string | null;
+    expires?: string | null;
+    policy_id?: string;
+    decision_id?: string;
 }
 export interface OperationRow {
     key: string;
@@ -83,6 +96,10 @@ export declare class Journal {
     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;
+    captureRevoked(policy: string, decision: string): boolean;
+    assertCaptureAuthorization(authorization: NonNullable<Plan["capture_authorization"]>): void;
+    recordCaptureAuthorization(key: string, fingerprint: string, authorization: NonNullable<Plan["capture_authorization"]>, validFrom: string | null, expires: string | null): void;
+    revokeCaptureAuthorization(key: string, fingerprint: string, policy: string, decision: string): 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;

package/dist/journal.js

@@ -47,6 +47,13 @@ export class Journal {
       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));
+      CREATE TABLE IF NOT EXISTS purra_mem0_capture_authorizations (
+        scope TEXT NOT NULL, policy TEXT NOT NULL, decision TEXT NOT NULL,
+        authorization TEXT NOT NULL, valid_from TEXT, expires TEXT,
+        PRIMARY KEY(scope,policy,decision));
+      CREATE TABLE IF NOT EXISTS purra_mem0_capture_revocations (
+        scope TEXT NOT NULL, policy TEXT NOT NULL, decision TEXT NOT NULL,
+        PRIMARY KEY(scope,policy,decision));
     `);
         this.transaction(() => {
             this.db.prepare("INSERT OR IGNORE INTO purra_mem0_info VALUES ('store',?)").run(randomUUID().replaceAll("-", ""));
@@ -127,6 +134,8 @@ export class Journal {
                 this.assertSnapshot(op.plan);
             if (op && op.plan.kind !== "delete" && op.plan.meta)
                 this.assertSource(op.plan.meta);
+            if (op?.plan.capture_authorization)
+                this.assertCaptureAuthorization(op.plan.capture_authorization);
             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"]
@@ -187,6 +196,63 @@ export class Journal {
             }
         });
     }
+    captureRevoked(policy, decision) {
+        return !!this.db.prepare("SELECT 1 FROM purra_mem0_capture_revocations WHERE scope=? AND policy=? AND decision=?")
+            .get(this.scope, policy, decision);
+    }
+    assertCaptureAuthorization(authorization) {
+        if (this.captureRevoked(authorization.policy_id, authorization.decision_id))
+            throw new MemoryError("memory_capture_authorization_revoked");
+        const row = this.db.prepare("SELECT authorization,valid_from,expires FROM purra_mem0_capture_authorizations WHERE scope=? AND policy=? AND decision=?")
+            .get(this.scope, authorization.policy_id, authorization.decision_id);
+        if (!row || JSON.stringify(JSON.parse(row.authorization)) !== JSON.stringify(authorization)) {
+            throw new MemoryError("memory_capture_authorization_unavailable");
+        }
+        const now = Date.now();
+        if (row.valid_from !== null && Date.parse(row.valid_from) > now)
+            throw new MemoryError("memory_capture_authorization_not_yet_valid");
+        if (row.expires !== null && Date.parse(row.expires) <= now)
+            throw new MemoryError("memory_capture_authorization_expired");
+    }
+    recordCaptureAuthorization(key, fingerprint, authorization, validFrom, expires) {
+        this.transaction(() => {
+            const previous = this.operation(key);
+            if (previous) {
+                if (previous.fingerprint !== fingerprint)
+                    throw new MemoryError("memory_idempotency_conflict");
+                return;
+            }
+            if (this.captureRevoked(authorization.policy_id, authorization.decision_id))
+                throw new MemoryError("memory_capture_authorization_revoked");
+            const row = this.db.prepare("SELECT authorization,valid_from,expires FROM purra_mem0_capture_authorizations WHERE scope=? AND policy=? AND decision=?")
+                .get(this.scope, authorization.policy_id, authorization.decision_id);
+            if (row && (JSON.stringify(JSON.parse(row.authorization)) !== JSON.stringify(authorization)
+                || row.valid_from !== validFrom || row.expires !== expires))
+                throw new MemoryError("memory_capture_authorization_conflict");
+            const plan = { kind: "record_capture_authorization", target: null, meta: null,
+                capture_authorization: authorization, valid_from: validFrom, expires };
+            this.db.prepare("INSERT INTO purra_mem0_ops VALUES (?,?,?,'complete',?,'[]')").run(this.scope, key, fingerprint, JSON.stringify(plan));
+            if (!row)
+                this.db.prepare("INSERT INTO purra_mem0_capture_authorizations VALUES (?,?,?,?,?,?)")
+                    .run(this.scope, authorization.policy_id, authorization.decision_id, JSON.stringify(authorization), validFrom, expires);
+        });
+    }
+    revokeCaptureAuthorization(key, fingerprint, policy, decision) {
+        this.transaction(() => {
+            const previous = this.operation(key);
+            if (previous) {
+                if (previous.fingerprint !== fingerprint)
+                    throw new MemoryError("memory_idempotency_conflict");
+                return;
+            }
+            const plan = { kind: "revoke_capture_authorization", target: null, meta: null, policy_id: policy, decision_id: decision };
+            this.db.prepare("INSERT INTO purra_mem0_ops VALUES (?,?,?,'complete',?,'[]')").run(this.scope, key, fingerprint, JSON.stringify(plan));
+            if (!this.captureRevoked(policy, decision)) {
+                this.db.prepare("INSERT INTO purra_mem0_capture_revocations VALUES (?,?,?)").run(this.scope, policy, decision);
+                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;
@@ -212,6 +278,8 @@ export class Journal {
                 throw new MemoryError("memory_context_stale");
             if (plan.review_key !== undefined)
                 this.assertSnapshot(this.reviewPlan(plan.review_key));
+            if (plan.capture_authorization !== undefined)
+                this.assertCaptureAuthorization(plan.capture_authorization);
             const records = [], now = Date.now();
             for (const [index, ref] of refs.entries()) {
                 const row = this.item(ref.id);

package/dist/memory.d.ts

@@ -36,6 +36,13 @@ export interface MemorySource {
     readonly id: string;
     readonly revision: string;
 }
+export interface MemoryCaptureAuthorization {
+    readonly intentDigest: string;
+    readonly policyId: string;
+    readonly policyRevision: string;
+    readonly principalId: string;
+    readonly decisionId: 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 {
@@ -74,6 +81,15 @@ export interface MemoryLinkPage {
     readonly next: string | null;
     readonly epoch: number;
 }
+export interface MemoryRelationEvidence {
+    readonly evidenceId: string;
+    readonly source: string;
+    readonly linkKey: string;
+    readonly from: MemoryRef;
+    readonly to: MemoryRef;
+    readonly relation: string;
+    readonly note: string;
+}
 export type MemoryResolution = {
     readonly items: readonly MemoryRef[];
     readonly reviewKey?: string;
@@ -112,11 +128,23 @@ interface SourceOptions extends WriteOptions {
     readonly expiresAt?: string | null;
     readonly metadata?: MemoryMetadata;
 }
+interface ExtractOptions extends SourceOptions {
+    readonly authorization?: MemoryCaptureAuthorization;
+}
 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;
+export declare function memoryCaptureIntent(messages: readonly {
+    role: "user" | "assistant";
+    content: string;
+}[], options: {
+    source: MemorySource;
+    metadata?: MemoryMetadata;
+    expiresAt?: string | null;
+    maxInputChars?: number;
+}): string;
 /** Host-owned SDK, immutable scope, persistent write fence. No automatic capture. */
 export declare class Mem0Memory implements Retriever {
     #private;
@@ -130,9 +158,17 @@ export declare class Mem0Memory implements Retriever {
         maxInputChars?: number;
         providers?: MemoryProviders;
     });
+    get maxInputChars(): number;
     operation(key: string): MemoryOperation | undefined;
+    recordCaptureAuthorization(authorizationValue: MemoryCaptureAuthorization, options: WriteOptions & {
+        validFrom?: string | null;
+        expiresAt?: string | null;
+    }): Promise<MemoryOperation>;
+    revokeCaptureAuthorization(policyIdValue: string, decisionIdValue: string, options: WriteOptions): Promise<MemoryOperation>;
     /** Verify content, then atomically keep one claim or quarantine a group. No SDK mutations. */
-    resolve(value: MemoryResolution, options: WriteOptions): Promise<MemoryOperation>;
+    resolve(value: MemoryResolution, options: WriteOptions & {
+        authorization?: MemoryCaptureAuthorization;
+    }): Promise<MemoryOperation>;
     /** Budgeted advice for a pending candidate; never activates memory. */
     link(from: MemoryRef, to: MemoryRef, relation: string, options: WriteOptions & {
         note?: string;
@@ -140,11 +176,21 @@ export declare class Mem0Memory implements Retriever {
     links(id: string, options?: {
         limit?: number;
         after?: string;
+        direction?: "both" | "incoming" | "outgoing";
+        relation?: string;
+        validOnly?: boolean;
         signal?: AbortSignal;
     }): Promise<MemoryLinkPage>;
+    relationEvidence(link: MemoryLink, options?: {
+        signal?: AbortSignal;
+    }): Promise<MemoryRelationEvidence>;
+    validateRelationEvidence(receipts: readonly MemoryRelationEvidence[], options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
     review(candidate: MemoryRef, options: WriteOptions & {
         limit?: number;
         instructions?: string;
+        authorization?: MemoryCaptureAuthorization;
     }): Promise<MemoryOperation>;
     /** Includes searches, reservations, late completions and unknown usage. */
     budgetUsage(): MemoryUsage | undefined;
@@ -185,7 +231,7 @@ export declare class Mem0Memory implements Retriever {
     extract(messages: readonly {
         role: "user" | "assistant";
         content: string;
-    }[], options: SourceOptions): Promise<MemoryOperation>;
+    }[], options: ExtractOptions): Promise<MemoryOperation>;
     update(id: string, text: string, options: SourceOptions & VersionOptions): Promise<MemoryOperation>;
     setState(id: string, state: MemoryRecord["state"], options: VersionOptions & {
         reason?: string | null;

package/dist/memory.js

@@ -74,6 +74,35 @@ function expiry(value) {
 function sourceCopy(source) {
     return Object.freeze({ id: requiredText(source?.id, "source id", 1024), revision: requiredText(source?.revision, "source revision", 512) });
 }
+function captureInput(messages, source, metadata, expiresAt, maxInput) {
+    const copiedSource = sourceCopy(source);
+    if (!Array.isArray(messages) || messages.length < 1 || messages.length > 100)
+        throw new TypeError("messages must contain 1 to 100 source messages");
+    const copied = messages.map(message => {
+        if (!message || Object.keys(message).sort().join(",") !== "content,role" || !["user", "assistant"].includes(message.role)) {
+            throw new TypeError("source messages may contain only user/assistant text");
+        }
+        return { role: message.role, content: requiredText(message.content, "message", maxInput) };
+    });
+    if (copied.reduce((total, message) => total + [...message.content].length, 0) > maxInput)
+        throw new TypeError("source messages exceed maxInputChars");
+    return { messages: copied, source: copiedSource, metadata: metadataCopy(metadata ?? {}), expiresAt: expiry(expiresAt) };
+}
+export function memoryCaptureIntent(messages, options) {
+    const maxInput = positiveInteger(options.maxInputChars ?? 32_000, "maxInputChars", 1_000_000);
+    const input = captureInput(messages, options.source, options.metadata, options.expiresAt, maxInput);
+    return "sha256:" + digest(["purra.mem0.capture-intent/v1", input.messages,
+        [input.source.id, input.source.revision], input.metadata, input.expiresAt]);
+}
+function authorizationCopy(value) {
+    if (!value || typeof value !== "object" || !/^sha256:[0-9a-f]{64}$/.test(value.intentDigest))
+        throw new TypeError("invalid capture authorization");
+    return Object.freeze({ intentDigest: value.intentDigest,
+        policyId: requiredText(value.policyId, "capture policy id", 512),
+        policyRevision: requiredText(value.policyRevision, "capture policy revision", 512),
+        principalId: requiredText(value.principalId, "capture principal id", 512),
+        decisionId: requiredText(value.decisionId, "capture decision id", 512) });
+}
 function resolutionCopy(value, limit = 100) {
     if (!value || !["independent", "duplicate", "supersede", "conflict"].includes(value.kind) || !Array.isArray(value.items)
         || value.items.length > limit || (value.kind === "independent" ? value.items.length !== 1 : value.items.length < 2)) {
@@ -154,6 +183,7 @@ export class Mem0Memory {
             throw error;
         }
     }
+    get maxInputChars() { return this.#maxInput; }
     async #call(work, signal) {
         if (this.#closed)
             throw new MemoryError("memory_closed");
@@ -189,21 +219,47 @@ export class Mem0Memory {
     operation(key) {
         const op = this.#journal.operation(requiredText(key, "operation key", 512));
         return op ? Object.freeze({ key, state: op.state, ids: Object.freeze(op.ids ?? []),
-            usage: op.plan.budget || ["revoke_source", "state", "annotate", "resolve", "link"].includes(op.plan.kind) ? this.#journal.usage("operation", key) : "unknown",
+            usage: op.plan.budget || ["revoke_source", "record_capture_authorization", "revoke_capture_authorization", "state", "annotate", "resolve", "link"].includes(op.plan.kind) ? this.#journal.usage("operation", key) : "unknown",
             ...(op.plan.resolution ? { resolution: resolutionCopy(op.plan.resolution) } : {}),
             ...(op.plan.review ? { review: reviewCopy(op.plan.review, key) } : {}) }) : undefined;
     }
+    async recordCaptureAuthorization(authorizationValue, options) {
+        const authorization = authorizationCopy(authorizationValue), key = requiredText(options.key, "operation key", 512);
+        const validFrom = expiry(options.validFrom), expires = expiry(options.expiresAt);
+        if (validFrom !== null && expires !== null && validFrom >= expires)
+            throw new TypeError("capture authorization expiry must follow validFrom");
+        const data = { intent_digest: authorization.intentDigest, policy_id: authorization.policyId,
+            policy_revision: authorization.policyRevision, principal_id: authorization.principalId, decision_id: authorization.decisionId };
+        const fingerprint = digest(["record_capture_authorization", data, validFrom, expires]);
+        return this.#call(async () => { this.#journal.recordCaptureAuthorization(key, fingerprint, data, validFrom, expires); return this.operation(key); }, options.signal);
+    }
+    async revokeCaptureAuthorization(policyIdValue, decisionIdValue, options) {
+        const policyId = requiredText(policyIdValue, "capture policy id", 512);
+        const decisionId = requiredText(decisionIdValue, "capture decision id", 512);
+        const key = requiredText(options.key, "operation key", 512);
+        const fingerprint = digest(["revoke_capture_authorization", policyId, decisionId]);
+        return this.#call(async () => { this.#journal.revokeCaptureAuthorization(key, fingerprint, policyId, decisionId); return this.operation(key); }, options.signal);
+    }
     /** Verify content, then atomically keep one claim or quarantine a group. No SDK mutations. */
     async resolve(value, options) {
         const resolution = resolutionCopy(value, this.#maxResults), key = requiredText(options.key, "operation key", 512);
         const reviewKey = resolution.reviewKey;
         const data = { kind: resolution.kind, items: resolution.items, keep: resolution.keep ?? null };
-        const fingerprint = digest(reviewKey === undefined ? ["resolve", data] : ["resolve", data, reviewKey]);
+        const authorization = options.authorization === undefined ? undefined : authorizationCopy(options.authorization);
+        const authorizationData = authorization === undefined ? undefined : { intent_digest: authorization.intentDigest,
+            policy_id: authorization.policyId, policy_revision: authorization.policyRevision,
+            principal_id: authorization.principalId, decision_id: authorization.decisionId };
+        const fingerprintInput = reviewKey === undefined ? ["resolve", data] : ["resolve", data, reviewKey];
+        if (authorizationData !== undefined)
+            fingerprintInput.push(authorizationData);
+        const fingerprint = digest(fingerprintInput);
         const plan = { kind: "resolve", target: null, meta: null, resolution };
         if (reviewKey !== undefined)
             plan.review_key = reviewKey;
         if (this.#providers)
             plan.budget = this.#providers.budget.key;
+        if (authorizationData !== undefined)
+            plan.capture_authorization = authorizationData;
         return this.#call(async () => {
             const previous = this.#journal.operation(key);
             if (previous) {
@@ -211,6 +267,8 @@ export class Mem0Memory {
                     throw new MemoryError("memory_idempotency_conflict");
                 return this.operation(key);
             }
+            if (authorizationData !== undefined)
+                this.#journal.assertCaptureAuthorization(authorizationData);
             const epoch = this.epoch;
             let refs = resolution.items;
             if (reviewKey !== undefined) {
@@ -277,17 +335,64 @@ export class Mem0Memory {
         requiredText(id, "memory id", 512);
         const limit = positiveInteger(options.limit ?? 20, "limit", this.#maxResults);
         const after = options.after === undefined ? undefined : requiredText(options.after, "cursor", 512);
+        const direction = options.direction === undefined ? "both" : options.direction;
+        if (!["both", "incoming", "outgoing"].includes(direction))
+            throw new TypeError("Invalid relation direction");
+        const relation = options.relation === undefined ? undefined : requiredText(options.relation, "relation", 64);
+        const validOnly = options.validOnly === undefined ? false : options.validOnly;
+        if (typeof validOnly !== "boolean")
+            throw new TypeError("validOnly must be boolean");
         return this.#call(async () => {
             const epoch = this.epoch, rows = this.#journal.links(id, after, limit + 1), items = [];
             for (const { key, data } of rows.slice(0, limit)) {
+                if (relation !== undefined && data.relation !== relation
+                    || direction === "incoming" && data.to.id !== id
+                    || direction === "outgoing" && data.from.id !== id)
+                    continue;
                 const from = await this.#read(data.from.id), to = await this.#read(data.to.id);
                 const valid = from !== undefined && to !== undefined && from.version === data.from.version && to.version === data.to.version;
+                if (validOnly && !valid)
+                    continue;
                 items.push(Object.freeze({ ...data, from: Object.freeze(data.from), to: Object.freeze(data.to), key, valid }));
             }
             this.assertEpoch(epoch);
             return Object.freeze({ items: Object.freeze(items), next: rows.length > limit ? rows[limit - 1].key : null, epoch });
         }, options.signal);
     }
+    async relationEvidence(link, options = {}) {
+        if (!link?.valid)
+            throw new MemoryError("memory_relation_stale");
+        const expected = { from: { id: requiredText(link.from.id, "from id", 512), version: positiveInteger(link.from.version, "from version", 2 ** 31 - 2) },
+            to: { id: requiredText(link.to.id, "to id", 512), version: positiveInteger(link.to.version, "to version", 2 ** 31 - 2) },
+            relation: requiredText(link.relation, "relation", 64), note: typeof link.note === "string" ? link.note : "" };
+        const key = requiredText(link.key, "link key", 512);
+        return this.#call(async () => {
+            const epoch = this.epoch;
+            const operation = this.#journal.operation(key);
+            if (!operation || operation.state !== "complete" || operation.plan.kind !== "link"
+                || !isDeepStrictEqual(operation.plan.link, expected))
+                throw new MemoryError("memory_relation_stale");
+            const [from, to] = await Promise.all([this.#read(expected.from.id), this.#read(expected.to.id)]);
+            if (!from || !to || from.version !== expected.from.version || to.version !== expected.to.version)
+                throw new MemoryError("memory_relation_stale");
+            this.assertEpoch(epoch);
+            return Object.freeze({ evidenceId: `mem0-relation:${this.#journal.store}:${digest([key, expected])}`,
+                source: "mem0-relation/" + this.#scope, linkKey: key, from: Object.freeze(expected.from),
+                to: Object.freeze(expected.to), relation: expected.relation, note: expected.note });
+        }, options.signal);
+    }
+    async validateRelationEvidence(receipts, options = {}) {
+        if (!Array.isArray(receipts) || receipts.length > this.#maxResults)
+            throw new TypeError("relation receipts must be a bounded array");
+        for (const receipt of receipts) {
+            if (receipt?.source !== "mem0-relation/" + this.#scope)
+                throw new MemoryError("memory_relation_stale");
+            const link = Object.freeze({ key: receipt.linkKey, from: receipt.from, to: receipt.to,
+                relation: receipt.relation, note: receipt.note, valid: true });
+            if (!isDeepStrictEqual(await this.relationEvidence(link, options), receipt))
+                throw new MemoryError("memory_relation_stale");
+        }
+    }
     async review(candidate, options) {
         if (!this.#providers)
             throw new MemoryError("memory_review_requires_managed");
@@ -297,10 +402,29 @@ export class Mem0Memory {
         if (typeof instructions !== "string" || [...instructions].length > 4000)
             throw new TypeError("instructions must be bounded host policy");
         const policy = REVIEW_PROMPT + (instructions ? "\nHost policy:\n" + instructions : "");
-        const fingerprint = digest(["review", ref, limit, policy]);
+        const authorization = options.authorization === undefined ? undefined : authorizationCopy(options.authorization);
+        const authorizationData = authorization === undefined ? undefined : { intent_digest: authorization.intentDigest,
+            policy_id: authorization.policyId, policy_revision: authorization.policyRevision,
+            principal_id: authorization.principalId, decision_id: authorization.decisionId };
+        const fingerprintInput = ["review", ref, limit, policy];
+        if (authorizationData !== undefined)
+            fingerprintInput.push(authorizationData);
+        const fingerprint = digest(fingerprintInput);
         const plan = { kind: "review", target: null, meta: null, budget: this.#providers.budget.key, policy_hash: digest(policy) };
+        if (authorizationData !== undefined)
+            plan.capture_authorization = authorizationData;
         return this.#call(async () => {
-            const previous = this.#journal.begin(key, fingerprint, plan);
+            let previous = this.#journal.operation(key);
+            if (previous) {
+                if (previous.fingerprint !== fingerprint)
+                    throw new MemoryError("memory_idempotency_conflict");
+                if (previous.state !== "complete")
+                    throw new MemoryError("memory_operation_unresolved");
+                return this.operation(key);
+            }
+            if (authorizationData !== undefined)
+                this.#journal.assertCaptureAuthorization(authorizationData);
+            previous = this.#journal.begin(key, fingerprint, plan);
             if (previous) {
                 if (previous.state !== "complete")
                     throw new MemoryError("memory_operation_unresolved");
@@ -436,6 +560,9 @@ export class Mem0Memory {
         const meta = row.meta;
         if (!internal && this.#journal.revoked(meta.purra_source, meta.purra_revision))
             return undefined;
+        if (!internal && meta.purra_capture_policy !== undefined
+            && this.#journal.captureRevoked(meta.purra_capture_policy, meta.purra_capture_decision))
+            return undefined;
         if (!internal && this.#journal.writing(id))
             throw new MemoryError("memory_write_busy");
         const result = await this.#client.get(id);
@@ -446,6 +573,9 @@ export class Mem0Memory {
             throw new MemoryError("memory_write_busy");
         if (!internal && this.#journal.revoked(meta.purra_source, meta.purra_revision))
             return undefined;
+        if (!internal && meta.purra_capture_policy !== undefined
+            && this.#journal.captureRevoked(meta.purra_capture_policy, meta.purra_capture_decision))
+            return undefined;
         const view = itemView(row);
         if (!includeInactive && !this.#active({ ...meta, purra_state: view.state }))
             return undefined;
@@ -520,17 +650,15 @@ export class Mem0Memory {
     async extract(messages, options) {
         if (!this.#allowInference)
             throw new MemoryError("memory_inference_disabled");
-        if (!Array.isArray(messages) || messages.length < 1 || messages.length > 100)
-            throw new TypeError("messages must contain 1 to 100 source messages");
-        const copied = messages.map(message => {
-            if (!message || Object.keys(message).sort().join(",") !== "content,role" || !["user", "assistant"].includes(message.role)) {
-                throw new TypeError("source messages may contain only user/assistant text");
-            }
-            return { role: message.role, content: requiredText(message.content, "message", this.#maxInput) };
-        });
-        if (copied.reduce((total, m) => total + [...m.content].length, 0) > this.#maxInput)
-            throw new TypeError("source messages exceed maxInputChars");
-        return this.#write("extract", copied, { ...options, state: "pending" });
+        const input = captureInput(messages, options.source, options.metadata, options.expiresAt, this.#maxInput);
+        const authorization = options.authorization === undefined ? undefined : authorizationCopy(options.authorization);
+        const expectedIntent = "sha256:" + digest(["purra.mem0.capture-intent/v1", input.messages,
+            [input.source.id, input.source.revision], input.metadata, input.expiresAt]);
+        if (authorization !== undefined && authorization.intentDigest !== expectedIntent) {
+            throw new MemoryError("memory_capture_authorization_mismatch");
+        }
+        return this.#write("extract", input.messages, { ...options, source: input.source, metadata: input.metadata,
+            expiresAt: input.expiresAt, ...(authorization === undefined ? {} : { authorization }), state: "pending" });
     }
     async update(id, text, options) {
         return this.#write("update", text, options, id, options.version);
@@ -587,13 +715,34 @@ export class Mem0Memory {
         const state = options.state ?? "active", reason = options.reason == null ? null : requiredText(options.reason, "state reason", 128);
         if (!["active", "pending", "disabled"].includes(state))
             throw new TypeError("invalid memory state");
-        const fingerprint = digest([kind, content, source ? [source.id, source.revision] : null, target, version, preserveExpiry ? "preserve" : expires,
-            preserveMetadata ? "preserve" : metadata, state, reason]);
+        const authorization = options.authorization === undefined ? null : authorizationCopy(options.authorization);
+        const authorizationData = authorization === null ? null : {
+            intent_digest: authorization.intentDigest, policy_id: authorization.policyId,
+            policy_revision: authorization.policyRevision, principal_id: authorization.principalId,
+            decision_id: authorization.decisionId,
+        };
+        const fingerprintInput = [kind, content, source ? [source.id, source.revision] : null, target, version,
+            preserveExpiry ? "preserve" : expires, preserveMetadata ? "preserve" : metadata, state, reason];
+        if (authorizationData !== null)
+            fingerprintInput.push(authorizationData);
+        const fingerprint = digest(fingerprintInput);
         const plan = { kind, target, meta: null };
+        if (authorizationData !== null)
+            plan.capture_authorization = authorizationData;
         if (this.#providers)
             plan.budget = this.#providers.budget.key;
         return this.#call(async () => {
-            const previous = this.#journal.begin(key, fingerprint, plan);
+            let previous = this.#journal.operation(key);
+            if (previous) {
+                if (previous.fingerprint !== fingerprint)
+                    throw new MemoryError("memory_idempotency_conflict");
+                if (previous.state !== "complete")
+                    throw new MemoryError("memory_operation_unresolved");
+                return this.operation(key);
+            }
+            if (authorizationData !== null)
+                this.#journal.assertCaptureAuthorization(authorizationData);
+            previous = this.#journal.begin(key, fingerprint, plan);
             if (previous) {
                 if (previous.state !== "complete")
                     throw new MemoryError("memory_operation_unresolved");
@@ -609,13 +758,17 @@ export class Mem0Memory {
                 if (source)
                     this.#journal.assertSource({ purra_source: source.id, purra_revision: source.revision });
                 let old;
+                let oldMeta;
                 if (target !== null) {
                     old = await this.#read(target, true, true);
                     if (!old)
                         throw new MemoryError("memory_not_found");
                     if (old.version !== version)
                         throw new MemoryError("memory_version_conflict");
+                    oldMeta = this.#journal.item(target).meta;
                 }
+                if (authorizationData !== null)
+                    this.#journal.assertCaptureAuthorization(authorizationData);
                 const meta = {
                     purra_scope: this.#scope, purra_store: this.#journal.store,
                     purra_operation: digest([this.#journal.store, this.#scope, key]),
@@ -628,10 +781,18 @@ export class Mem0Memory {
                     purra_reason: old ? old.reason : reason,
                     purra_created: old ? old.createdAt : new Date().toISOString(), purra_updated: new Date().toISOString(),
                 };
+                const capturePolicy = oldMeta?.purra_capture_policy ?? authorizationData?.policy_id;
+                const captureDecision = oldMeta?.purra_capture_decision ?? authorizationData?.decision_id;
+                if (capturePolicy !== undefined) {
+                    meta.purra_capture_policy = capturePolicy;
+                    meta.purra_capture_decision = captureDecision;
+                }
                 const desiredText = kind === "delete" ? old.text : content;
                 plan.meta = meta;
                 plan.hash = kind === "extract" ? null : digest(desiredText);
                 this.#journal.savePlan(key, plan);
+                if (authorizationData !== null)
+                    this.#journal.assertCaptureAuthorization(authorizationData);
                 dispatched = true;
                 let ids;
                 if (kind === "add" || kind === "extract") {

package/dist/workflow.d.ts

@@ -13,6 +13,8 @@ export declare class MemoryWorkflow {
         policy?: MemoryDecisionPolicy;
         policyRevision?: string;
         reviewLimit?: number;
+        capturePolicyId?: string;
+        capturePolicyRevision?: string;
     });
     capture(messages: Parameters<Mem0Memory["extract"]>[0], options: Parameters<Mem0Memory["extract"]>[1]): Promise<MemoryWorkflowResult>;
 }

package/dist/workflow.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
-import { Mem0Memory, requiredText, positiveInteger } from "./memory.js";
+import { Mem0Memory, memoryCaptureIntent, requiredText, positiveInteger } from "./memory.js";
+import { MemoryError } from "./journal.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 {
@@ -7,6 +8,7 @@ export class MemoryWorkflow {
     #policy;
     #revision;
     #limit;
+    #capturePolicy;
     constructor(memory, options = {}) {
         this.#memory = memory;
         this.#policy = options.policy;
@@ -14,9 +16,32 @@ export class MemoryWorkflow {
             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);
+        if ((options.capturePolicyId === undefined) !== (options.capturePolicyRevision === undefined)) {
+            throw new TypeError("capture policy id and revision must be configured together");
+        }
+        this.#capturePolicy = options.capturePolicyId === undefined ? undefined : Object.freeze({
+            id: requiredText(options.capturePolicyId, "capture policy id", 512),
+            revision: requiredText(options.capturePolicyRevision, "capture policy revision", 512),
+        });
     }
     async capture(messages, options) {
         const prefix = "workflow:" + digest(requiredText(options.key, "workflow key", 512));
+        if (!this.#capturePolicy) {
+            if (options.authorization !== undefined)
+                throw new TypeError("capture authorization requires a configured capture policy");
+        }
+        else {
+            if (options.authorization === undefined)
+                throw new MemoryError("memory_capture_authorization_required");
+            const intentOptions = { source: options.source, maxInputChars: this.#memory.maxInputChars,
+                ...(options.metadata === undefined ? {} : { metadata: options.metadata }),
+                ...(options.expiresAt === undefined ? {} : { expiresAt: options.expiresAt }) };
+            const intent = memoryCaptureIntent(messages, intentOptions);
+            if (options.authorization.intentDigest !== intent || options.authorization.policyId !== this.#capturePolicy.id
+                || options.authorization.policyRevision !== this.#capturePolicy.revision) {
+                throw new MemoryError("memory_capture_authorization_mismatch");
+            }
+        }
         const extraction = await this.#memory.extract(messages, { ...options, key: prefix + ":extract" });
         const resolutions = [];
         const pendingIds = [];
@@ -36,7 +61,8 @@ export class MemoryWorkflow {
                 if (!record || record.state !== "pending")
                     continue;
                 const reviewed = await this.#memory.review({ id, version: record.version }, {
-                    key: prefix + ":review:" + suffix, limit: this.#limit, ...signal,
+                    key: prefix + ":review:" + suffix, limit: this.#limit,
+                    ...(options.authorization === undefined ? {} : { authorization: options.authorization }), ...signal,
                 });
                 if (reviewed.state !== "complete" || !reviewed.review || !this.#policy) {
                     pendingIds.push(id);
@@ -50,7 +76,8 @@ export class MemoryWorkflow {
                 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 });
+                const resolved = await this.#memory.resolve(decision, { key: resolveKey,
+                    ...(options.authorization === undefined ? {} : { authorization: options.authorization }), ...signal });
                 resolutions.push(resolved);
                 if (resolved.state !== "complete")
                     pendingIds.push(id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "purra-mem0",
-  "version": "1.0.0",
+  "version": "1.0.4",
   "description": "Scoped Mem0 OSS memory integration for PurrA",
   "license": "MIT AND Apache-2.0",
   "type": "module",
@@ -69,7 +69,7 @@
     "mysql2": "^3.0.0",
     "@zilliz/milvus2-sdk-node": "^2.4.0 || ^3.0.0",
     "@aws-sdk/client-bedrock-runtime": ">=3.0.0 <3.968.0",
-    "purra": "1.0.0"
+    "purra": "1.0.4"
   },
   "devDependencies": {
     "@types/node": "22.20.1",
@@ -184,7 +184,7 @@
   "dependencies": {
     "axios": "^1.18.0",
     "openai": "^4.93.0",
-    "uuid": "^11.1.1",
+    "uuid": "^11.0.1",
     "zod": "^3.24.1"
   }
 }