@kindgi/memory 0.1.4 → 0.1.5

package/dist/errors.d.ts

@@ -10,7 +10,7 @@ import type { FactId, LogEntryId } from '@kindgi/types';
  * rejection modes (no-embedding-provider, unknown-embedding-model,
  * ambiguous-default-provider).
  */
-export type MemoryError = InvalidLogEntryError | InvalidFactError | FactNotFoundError | LogNotFoundError | EmbeddingError | RefreshHandlerMissingError | RetentionViolationError | PersistenceError;
+export type MemoryError = InvalidLogEntryError | InvalidFactError | FactNotFoundError | LogNotFoundError | EmbeddingError | RefreshHandlerMissingError | RetentionViolationError | ErasureInProgressError | PersistenceError;
 export interface InvalidLogEntryError {
     readonly code: 'invalid-log-entry';
     readonly message: string;
@@ -50,6 +50,15 @@ export interface RetentionViolationError {
     readonly factId: FactId;
     readonly reason: 'legal-hold' | 'keep-until' | 'keep-days';
 }
+/**
+ * A write for a person (by scope or subject), or a conversation, that an
+ * erasure in progress holds: nothing new lands for them until it
+ * completes.
+ */
+export interface ErasureInProgressError {
+    readonly code: 'erasure-in-progress';
+    readonly message: string;
+}
 export interface PersistenceError {
     readonly code: 'persistence-error';
     readonly message: string;

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAExD;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,GACnB,oBAAoB,GACpB,gBAAgB,GAChB,iBAAiB,GACjB,gBAAgB,GAChB,cAAc,GACd,0BAA0B,GAC1B,uBAAuB,GACvB,gBAAgB,CAAC;AAErB,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,GAAG,WAAW,CAAC;CAC5D;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAExD;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,GACnB,oBAAoB,GACpB,gBAAgB,GAChB,iBAAiB,GACjB,gBAAgB,GAChB,cAAc,GACd,0BAA0B,GAC1B,uBAAuB,GACvB,sBAAsB,GACtB,gBAAgB,CAAC;AAErB,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,GAAG,WAAW,CAAC;CAC5D;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB"}

package/dist/fusion.d.ts

@@ -0,0 +1,20 @@
+/** The `k` of reciprocal rank fusion: how much the top ranks dominate (60 is the usual choice). */
+export declare const RRF_K = 60;
+/** One fused item: its score and its 1-based rank in each leg that found it. */
+export interface Fused<T> {
+    readonly item: T;
+    /** `Σ 1 / (k + rank)` over the legs that found it. */
+    readonly score: number;
+    /** Its rank in each leg, by the leg's name; absent where that leg didn't find it. */
+    readonly ranks: Readonly<Record<string, number>>;
+}
+/**
+ * Reciprocal rank fusion of ranked result lists ("legs", each best
+ * first): every item scores `Σ 1 / (k + rank)` over the legs that found
+ * it, so agreement between legs wins and raw scores (a full-text rank, a
+ * cosine similarity) never need to be compared. Ties keep the order of
+ * the first leg that found them. Items are matched across legs by `key`;
+ * the first leg's copy of an item is kept.
+ */
+export declare function fuseByRank<T>(legs: Readonly<Record<string, readonly T[]>>, key: (item: T) => string, k?: number): readonly Fused<T>[];
+//# sourceMappingURL=fusion.d.ts.map

package/dist/fusion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fusion.d.ts","sourceRoot":"","sources":["../src/fusion.ts"],"names":[],"mappings":"AAGA,mGAAmG;AACnG,eAAO,MAAM,KAAK,KAAK,CAAC;AAExB,gFAAgF;AAChF,MAAM,WAAW,KAAK,CAAC,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qFAAqF;IACrF,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAClD;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,CAAC,CAAC,EAC5C,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,EACxB,CAAC,GAAE,MAAc,GAChB,SAAS,KAAK,CAAC,CAAC,CAAC,EAAE,CAsBrB"}

package/dist/fusion.js

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/** The `k` of reciprocal rank fusion: how much the top ranks dominate (60 is the usual choice). */
+export const RRF_K = 60;
+/**
+ * Reciprocal rank fusion of ranked result lists ("legs", each best
+ * first): every item scores `Σ 1 / (k + rank)` over the legs that found
+ * it, so agreement between legs wins and raw scores (a full-text rank, a
+ * cosine similarity) never need to be compared. Ties keep the order of
+ * the first leg that found them. Items are matched across legs by `key`;
+ * the first leg's copy of an item is kept.
+ */
+export function fuseByRank(legs, key, k = RRF_K) {
+    const fused = new Map();
+    let seen = 0;
+    for (const [leg, items] of Object.entries(legs)) {
+        items.forEach((item, i) => {
+            const id = key(item);
+            const rank = i + 1;
+            const entry = fused.get(id);
+            if (entry === undefined) {
+                fused.set(id, { item, score: 1 / (k + rank), ranks: { [leg]: rank }, first: seen++ });
+            }
+            else if (entry.ranks[leg] === undefined) {
+                entry.score += 1 / (k + rank);
+                entry.ranks[leg] = rank;
+            }
+        });
+    }
+    return [...fused.values()]
+        .sort((a, b) => b.score - a.score || a.first - b.first)
+        .map(({ item, score, ranks }) => ({ item, score, ranks }));
+}
+//# sourceMappingURL=fusion.js.map

package/dist/fusion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fusion.js","sourceRoot":"","sources":["../src/fusion.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC,mGAAmG;AACnG,MAAM,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;AAWxB;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CACxB,IAA4C,EAC5C,GAAwB,EACxB,IAAY,KAAK;IAEjB,MAAM,KAAK,GAAG,IAAI,GAAG,EAGlB,CAAC;IACJ,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;YACxB,MAAM,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;YACrB,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;YACnB,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC5B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;YACxF,CAAC;iBAAM,IAAI,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,SAAS,EAAE,CAAC;gBAC1C,KAAK,CAAC,KAAK,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;gBAC9B,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;YAC1B,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IACD,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;SACvB,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;SACtD,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;AAC/D,CAAC"}

package/dist/index.d.ts

@@ -1,7 +1,13 @@
-export type { Fact, MemoryScope, Retention, Source, SourceFreshness, SourceRefresh, } from './types.js';
+export type { Fact, FactAttribution, FactGeneratedBy, FactInvalidationReason, FactSubject, FactTrust, MemoryReaders, MemoryScope, Retention, Source, SourceFreshness, SourceRefresh, } from './types.js';
+export { isReadableBy } from './readers.js';
+export { isRecallReadableBy } from './recall.js';
+export type { RecallHit, RecallRow, RecallSelection, RecalledMessage, SearchConversationsInput, } from './recall.js';
+export { RRF_K, fuseByRank } from './fusion.js';
+export type { Fused } from './fusion.js';
 export { LOG_KINDS } from './log.js';
 export type { LogEntry, LogKind } from './log.js';
 export type { RetrievalHit } from './retrieval.js';
-export type { FactNotFoundError, InvalidFactError, InvalidLogEntryError, LogNotFoundError, MemoryError, PersistenceError, RefreshHandlerMissingError, RetentionViolationError, } from './errors.js';
+export type { ErasureInProgressError, FactNotFoundError, InvalidFactError, InvalidLogEntryError, LogNotFoundError, MemoryError, PersistenceError, RefreshHandlerMissingError, RetentionViolationError, } from './errors.js';
+export type { MemoryRememberBinding, RememberFactInput, RememberFactResult, RememberReviewReason, RememberedContent, } from './remember.js';
 export type { AppendLogInput, ListFactsInput, MemoryQueryBinding, ReadLogInput, SearchByKeywordInput, SearchBySemanticInput, } from './memory-binding.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,YAAY,EACV,IAAI,EACJ,WAAW,EACX,SAAS,EACT,MAAM,EACN,eAAe,EACf,aAAa,GACd,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,YAAY,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAGlD,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGnD,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EAChB,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,aAAa,CAAC;AAGrB,YAAY,EACV,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,YAAY,EACV,IAAI,EACJ,eAAe,EACf,eAAe,EACf,sBAAsB,EACtB,WAAW,EACX,SAAS,EACT,aAAa,EACb,WAAW,EACX,SAAS,EACT,MAAM,EACN,eAAe,EACf,aAAa,GACd,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAG5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,YAAY,EACV,SAAS,EACT,SAAS,EACT,eAAe,EACf,eAAe,EACf,wBAAwB,GACzB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAChD,YAAY,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAGzC,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,YAAY,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAGlD,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGnD,YAAY,EACV,sBAAsB,EACtB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EAChB,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,aAAa,CAAC;AAGrB,YAAY,EACV,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAGvB,YAAY,EACV,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -1,5 +1,11 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2026 Kindgi Inc.
+// ============ The scope guard ============
+export { isReadableBy } from './readers.js';
+// ============ Recalling earlier conversations ============
+export { isRecallReadableBy } from './recall.js';
+// ============ Hybrid retrieval ============
+export { RRF_K, fuseByRank } from './fusion.js';
 // ============ Log types ============
 export { LOG_KINDS } from './log.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAYjC,sCAAsC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAkBjC,4CAA4C;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,4DAA4D;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AASjD,6CAA6C;AAC7C,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGhD,sCAAsC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC"}

package/dist/log.d.ts

@@ -27,5 +27,19 @@ export interface LogEntry {
     readonly prevHash: string;
     readonly entryHash: string;
     readonly causedByLogId?: string;
+    /**
+     * How `entryHash` was computed. `2`: over the payload's hash
+     * (`contentHash`), so a payload cleared by an erasure still verifies.
+     * `1` (entries from before): over the payload itself. Absent: 1.
+     */
+    readonly hashVersion?: 1 | 2;
+    /** When an erasure cleared `payload` (its `contentHash` stays). */
+    readonly payloadErasedAt?: Timestamp;
+    /**
+     * The salt of a v2 entry's `contentHash`: the hash is over the payload
+     * and this salt, so it can't confirm a guessed payload. An erasure
+     * clears it with the payload.
+     */
+    readonly payloadSalt?: string;
 }
 //# sourceMappingURL=log.d.ts.map

package/dist/log.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAElE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,8FAA8F;AAC9F,eAAO,MAAM,SAAS,4OAcZ,CAAC;AAEX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjD;;;;;;;;GAQG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC"}
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAElE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,8FAA8F;AAC9F,eAAO,MAAM,SAAS,4OAcZ,CAAC;AAEX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjD;;;;;;;;GAQG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B"}

package/dist/memory-binding.d.ts

@@ -1,6 +1,7 @@
 import type { EmbeddingProviderRegistry } from '@kindgi/embedding';
-import type { Fact, LogEntry, LogKind, MemoryError, MemoryScope, RetrievalHit } from '@kindgi/memory';
+import type { Fact, LogEntry, LogKind, MemoryError, MemoryReaders, MemoryScope, RetrievalHit } from '@kindgi/memory';
 import type { Result, RunId, TenantId } from '@kindgi/types';
+import type { RecallHit, SearchConversationsInput } from './recall.js';
 /**
  * Caller-plugged data-access surface for the memory subsystem. Agent
  * code routes its memory reads through this binding — @kindgi/agents
@@ -21,7 +22,9 @@ import type { Result, RunId, TenantId } from '@kindgi/types';
 export interface MemoryQueryBinding {
     /**
      * List facts filtered by tenant, type, and scope, capped by `limit`
-     * (no pagination cursor). Default: latest version per `(type, id)`.
+     * (no pagination cursor): each fact's current revision, never one
+     * pending review, and only what `readers` may see (the guard, applied
+     * in the query before the limit).
      */
     listFacts<TContent = unknown>(input: ListFactsInput): Promise<Result<readonly Fact<TContent>[], MemoryError>>;
     /**
@@ -36,6 +39,18 @@ export interface MemoryQueryBinding {
      * embeds the query; the impl runs the vector search.
      */
     searchBySemantic<TContent = unknown>(input: SearchBySemanticInput): Promise<Result<readonly RetrievalHit<TContent>[], MemoryError>>;
+    /**
+     * Recall messages of earlier conversations (a retrieval intent with
+     * `source: 'conversations'`): what `readers` may recall
+     * (`isRecallReadableBy`), narrowed by `selections`, newest first
+     * (`list`), by full-text rank (`keyword`) or by meaning (`semantic`).
+     * Never a comparison's replay conversation (an eval run's replay turn
+     * opens one): its messages are no one's earlier conversation.
+     * Optional: without it, such an intent recalls nothing and its turn
+     * journals why. `semantic` without embeddings answers
+     * `embedding-unavailable`, as fact search does.
+     */
+    searchConversations?(input: SearchConversationsInput): Promise<Result<readonly RecallHit[], MemoryError>>;
     /**
      * Append one entry to the run's hash-chained log. The implementation
      * assigns `sequence` and `prevHash` / `entryHash` atomically; the
@@ -53,8 +68,15 @@ export interface MemoryQueryBinding {
 export interface ListFactsInput {
     readonly tenantId: TenantId;
     readonly type?: string;
+    /** Narrows within what `readers` may see: every given key must match. */
     readonly scope?: Partial<MemoryScope>;
+    /**
+     * What the reader may see (the scope guard), applied inside the query
+     * before any limit. Absent: only tenant-wide facts.
+     */
+    readonly readers?: MemoryReaders;
     readonly limit?: number;
+    /** Ignored: a list holds each fact's current revision. */
     readonly latestOnly?: boolean;
 }
 export interface SearchByKeywordInput {
@@ -62,6 +84,11 @@ export interface SearchByKeywordInput {
     readonly query: string;
     readonly type?: string;
     readonly scope?: Partial<MemoryScope>;
+    /**
+     * What the reader may see (the scope guard), applied inside the query
+     * before any limit. Absent: only tenant-wide facts.
+     */
+    readonly readers?: MemoryReaders;
     readonly topK?: number;
 }
 export interface SearchBySemanticInput {
@@ -75,6 +102,11 @@ export interface SearchBySemanticInput {
     readonly embeddingModel?: string;
     readonly type?: string;
     readonly scope?: Partial<MemoryScope>;
+    /**
+     * What the reader may see (the scope guard), applied inside the query
+     * before any limit. Absent: only tenant-wide facts.
+     */
+    readonly readers?: MemoryReaders;
     readonly topK?: number;
 }
 export interface AppendLogInput {

package/dist/memory-binding.d.ts.map

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

package/dist/readers.d.ts

@@ -0,0 +1,18 @@
+import type { MemoryReaders, MemoryScope } from './types.js';
+/**
+ * Whether `readers` may see a fact in `scope`: the scope guard, as every
+ * memory binding applies it inside its queries (a SQL binding's guard
+ * must agree with this one, case for case).
+ *
+ * Each container the scope names must be one the readers have:
+ *   - its project (or one they act in for all end users,
+ *     `onBehalfOfProjectIds`);
+ *   - its org, for an org-wide fact (no project);
+ *   - its user;
+ *   - its participant, or the project on behalf of all of them;
+ *   - its thread, or the project on behalf of all of them.
+ * A fact naming none of them is tenant-wide: every reader sees it. The
+ * session is not a container.
+ */
+export declare function isReadableBy(scope: MemoryScope, readers: MemoryReaders): boolean;
+//# sourceMappingURL=readers.d.ts.map

package/dist/readers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readers.d.ts","sourceRoot":"","sources":["../src/readers.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE7D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAoBhF"}

package/dist/readers.js

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * Whether `readers` may see a fact in `scope`: the scope guard, as every
+ * memory binding applies it inside its queries (a SQL binding's guard
+ * must agree with this one, case for case).
+ *
+ * Each container the scope names must be one the readers have:
+ *   - its project (or one they act in for all end users,
+ *     `onBehalfOfProjectIds`);
+ *   - its org, for an org-wide fact (no project);
+ *   - its user;
+ *   - its participant, or the project on behalf of all of them;
+ *   - its thread, or the project on behalf of all of them.
+ * A fact naming none of them is tenant-wide: every reader sees it. The
+ * session is not a container.
+ */
+export function isReadableBy(scope, readers) {
+    if (readers.all === true)
+        return true;
+    const project = scope.projectId;
+    const has = (ids, id) => ids?.includes(id) === true;
+    const onBehalf = project !== undefined && has(readers.onBehalfOfProjectIds, project);
+    if (project !== undefined && !(has(readers.projectIds, project) || onBehalf))
+        return false;
+    if (project === undefined && scope.orgId !== undefined && !has(readers.orgIds, scope.orgId)) {
+        return false;
+    }
+    if (scope.userId !== undefined && !has(readers.userIds, scope.userId))
+        return false;
+    if (scope.participantId !== undefined &&
+        !(has(readers.participantIds, scope.participantId) || onBehalf)) {
+        return false;
+    }
+    if (scope.threadId !== undefined && !(has(readers.threadIds, scope.threadId) || onBehalf)) {
+        return false;
+    }
+    return true;
+}
+//# sourceMappingURL=readers.js.map

package/dist/readers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readers.js","sourceRoot":"","sources":["../src/readers.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAIjC;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAAC,KAAkB,EAAE,OAAsB;IACrE,IAAI,OAAO,CAAC,GAAG,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACtC,MAAM,OAAO,GAAG,KAAK,CAAC,SAAS,CAAC;IAChC,MAAM,GAAG,GAAG,CAAI,GAA6B,EAAE,EAAK,EAAE,EAAE,CAAC,GAAG,EAAE,QAAQ,CAAC,EAAE,CAAC,KAAK,IAAI,CAAC;IACpF,MAAM,QAAQ,GAAG,OAAO,KAAK,SAAS,IAAI,GAAG,CAAC,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAAC;IACrF,IAAI,OAAO,KAAK,SAAS,IAAI,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,IAAI,QAAQ,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3F,IAAI,OAAO,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5F,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IACpF,IACE,KAAK,CAAC,aAAa,KAAK,SAAS;QACjC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,cAAc,EAAE,KAAK,CAAC,aAAa,CAAC,IAAI,QAAQ,CAAC,EAC/D,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,KAAK,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,EAAE,CAAC;QAC1F,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/recall.d.ts

@@ -0,0 +1,100 @@
+import type { EmbeddingProviderRegistry } from '@kindgi/embedding';
+import type { ScopeSegment, TenantId, Timestamp } from '@kindgi/types';
+import type { MemoryReaders } from './types.js';
+/**
+ * One message of an earlier conversation, as recall finds it: a user's
+ * message or an agent's answer (tool calls and the turns that made them
+ * are not indexed), with the indexed messages either side for context.
+ */
+export interface RecalledMessage {
+    readonly conversationId: string;
+    readonly sequence: number;
+    readonly role: 'user' | 'agent';
+    readonly text: string;
+    readonly createdAt: Timestamp;
+    /** The agent the conversation was with. */
+    readonly agentId: string;
+    readonly projectId?: string;
+    /** The conversation's end user (the app's own id for them). */
+    readonly participantId?: string;
+    /** The Kindgi user its turns acted for, when one did. */
+    readonly userId?: string;
+    /** The indexed message (of the roles recalled) just before it in its conversation, if any. */
+    readonly before?: {
+        readonly role: 'user' | 'agent';
+        readonly text: string;
+    };
+    /** The indexed message (of the roles recalled) just after it, if any. */
+    readonly after?: {
+        readonly role: 'user' | 'agent';
+        readonly text: string;
+    };
+}
+/** A recalled message and how well it matched (a full-text rank or a cosine similarity). */
+export interface RecallHit {
+    readonly message: RecalledMessage;
+    readonly score?: number;
+}
+/**
+ * What one recall narrows to, within what the readers may see. Always
+ * one agent's conversations. Every other field given must match.
+ */
+export interface RecallSelection {
+    readonly agentId: string;
+    /** Only this conversation (with `beforeSequence`: its messages older than that). */
+    readonly conversationId?: string;
+    readonly beforeSequence?: number;
+    /** Every conversation but this one. */
+    readonly excludeConversationId?: string;
+    readonly participantId?: string;
+    readonly userId?: string;
+    readonly projectId?: string;
+    /** Conversations whose segment path starts with this one (the same customer). */
+    readonly segmentsPrefix?: readonly ScopeSegment[];
+}
+export interface SearchConversationsInput {
+    readonly tenantId: TenantId;
+    /** What the reader may see (`isRecallReadableBy`), applied in the query before the limit. */
+    readonly readers: MemoryReaders;
+    /** The narrowings, merged: a message matching any of them. */
+    readonly selections: readonly RecallSelection[];
+    /** `list`: the newest first, no query. `keyword`: full-text. `semantic`: by meaning. */
+    readonly mode: 'list' | 'keyword' | 'semantic';
+    /**
+     * Whose messages: the hits and their neighbours alike. Default
+     * `['user']`, the people's own words; an agent's earlier answers only
+     * when asked for.
+     */
+    readonly roles?: readonly ('user' | 'agent')[];
+    readonly query?: string;
+    /** For `semantic`: the registry the query is embedded with. */
+    readonly embeddingRegistry?: EmbeddingProviderRegistry;
+    readonly embeddingModel?: string;
+    readonly topK: number;
+}
+/** The containers a recalled message's conversation is in, as the recall guard sees them. */
+export interface RecallRow {
+    readonly conversationId: string;
+    readonly projectId?: string;
+    readonly participantId?: string;
+    readonly userId?: string;
+}
+/**
+ * Whether `readers` may recall a message of this conversation: the recall
+ * guard, as every binding applies it inside its query (a SQL binding's
+ * guard must agree with this one, case for case). Stricter than facts'
+ * (`isReadableBy`): a conversation is always someone's.
+ *   - **Its project:** one the readers have, or act in for every end user
+ *     (`onBehalfOfProjectIds`). A conversation without a project passes
+ *     only by its person or the conversation itself.
+ *   - **Its person:** its end user when it has one, else the Kindgi user
+ *     its turns acted for. The readers must be that person
+ *     (`participantIds`, or `userIds` for a conversation without an end
+ *     user), be in the conversation (`threadIds`), or act in its project
+ *     for every end user. An app's credential is one Kindgi user for all
+ *     of its end users, so the user never opens an end user's
+ *     conversation. A conversation naming no person is readable only
+ *     from inside it, or for its whole project.
+ */
+export declare function isRecallReadableBy(row: RecallRow, readers: MemoryReaders): boolean;
+//# sourceMappingURL=recall.d.ts.map

package/dist/recall.d.ts.map

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

package/dist/recall.js

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * Whether `readers` may recall a message of this conversation: the recall
+ * guard, as every binding applies it inside its query (a SQL binding's
+ * guard must agree with this one, case for case). Stricter than facts'
+ * (`isReadableBy`): a conversation is always someone's.
+ *   - **Its project:** one the readers have, or act in for every end user
+ *     (`onBehalfOfProjectIds`). A conversation without a project passes
+ *     only by its person or the conversation itself.
+ *   - **Its person:** its end user when it has one, else the Kindgi user
+ *     its turns acted for. The readers must be that person
+ *     (`participantIds`, or `userIds` for a conversation without an end
+ *     user), be in the conversation (`threadIds`), or act in its project
+ *     for every end user. An app's credential is one Kindgi user for all
+ *     of its end users, so the user never opens an end user's
+ *     conversation. A conversation naming no person is readable only
+ *     from inside it, or for its whole project.
+ */
+export function isRecallReadableBy(row, readers) {
+    if (readers.all === true)
+        return true;
+    const has = (ids, id) => id !== undefined && ids?.includes(id) === true;
+    const project = row.projectId;
+    const onBehalf = has(readers.onBehalfOfProjectIds, project);
+    if (project !== undefined &&
+        !(has(readers.projectIds, project) || onBehalf)) {
+        return false;
+    }
+    const isPerson = row.participantId !== undefined
+        ? has(readers.participantIds, row.participantId)
+        : has(readers.userIds, row.userId);
+    return (isPerson ||
+        has(readers.threadIds, row.conversationId) ||
+        onBehalf);
+}
+//# sourceMappingURL=recall.js.map

package/dist/recall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall.js","sourceRoot":"","sources":["../src/recall.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAoFjC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAc,EAAE,OAAsB;IACvE,IAAI,OAAO,CAAC,GAAG,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACtC,MAAM,GAAG,GAAG,CAAI,GAA6B,EAAE,EAAiB,EAAE,EAAE,CAClE,EAAE,KAAK,SAAS,IAAI,GAAG,EAAE,QAAQ,CAAC,EAAE,CAAC,KAAK,IAAI,CAAC;IACjD,MAAM,OAAO,GAAG,GAAG,CAAC,SAAS,CAAC;IAC9B,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,oBAAqD,EAAE,OAAO,CAAC,CAAC;IAC7F,IACE,OAAO,KAAK,SAAS;QACrB,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,UAA2C,EAAE,OAAO,CAAC,IAAI,QAAQ,CAAC,EAChF,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,QAAQ,GACZ,GAAG,CAAC,aAAa,KAAK,SAAS;QAC7B,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,cAAc,EAAE,GAAG,CAAC,aAAa,CAAC;QAChD,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,OAAwC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACxE,OAAO,CACL,QAAQ;QACR,GAAG,CAAC,OAAO,CAAC,SAA0C,EAAE,GAAG,CAAC,cAAc,CAAC;QAC3E,QAAQ,CACT,CAAC;AACJ,CAAC"}

package/dist/remember.d.ts

@@ -0,0 +1,76 @@
+import type { Result, TenantId, Timestamp } from '@kindgi/types';
+import type { MemoryError } from './errors.js';
+import type { Fact, FactSubject, MemoryScope } from './types.js';
+/**
+ * What an agent remembers through its `remember` tool: a short text, and
+ * optionally the slot (`key`) it fills. A new value for a slot the same
+ * agent filled before, for the same type and scope, is that fact's next
+ * revision.
+ */
+export interface RememberedContent {
+    readonly text: string;
+    readonly key?: string;
+}
+/** Why a remembered fact waits for a person before any read sees it. */
+export type RememberReviewReason = 
+/** The declared scope reaches beyond one person (`same-project`, `tenant`). */
+'wide-scope'
+/** The text reads like an instruction (always/never/ignore, a URL, a tool name). */
+ | 'instruction-like';
+/**
+ * One `remember` call, as the agent layer builds it from the agent's
+ * declaration and the run. The model chooses only the type (among those
+ * declared), the text, the slot and how long it's true; never the scope,
+ * the trust or whom it's attributed to.
+ */
+export interface RememberFactInput {
+    readonly tenantId: TenantId;
+    /** Where it's stored: the declaration's scope, filled from the run. */
+    readonly scope: MemoryScope;
+    readonly type: string;
+    readonly content: RememberedContent;
+    /** Whom it's about: the conversation's end user, else the run's user. */
+    readonly subjects: readonly FactSubject[];
+    /** The agent version that remembered it. */
+    readonly agent: {
+        readonly id: string;
+        readonly version: string;
+    };
+    /**
+     * The call that wrote it. A second call with the same run and tool call
+     * (a step re-run after a crash) returns the fact the first one wrote.
+     */
+    readonly generatedBy: {
+        readonly runId: string;
+        readonly stepId?: string;
+        readonly toolCallId: string;
+    };
+    /** How long it's kept unless a person verifies it (retention `keepDays`). */
+    readonly keepDays: number;
+    /** When it stops being true in the world, if the model said so. */
+    readonly validUntil?: Timestamp;
+    /** Present when a person must approve it first; no read sees it until then. */
+    readonly review?: {
+        readonly reasons: readonly RememberReviewReason[];
+    };
+}
+export interface RememberFactResult {
+    /** The revision written: `trust: unverified`, `review: pending` while it waits. */
+    readonly fact: Fact<RememberedContent>;
+    /**
+     * `created`: a new fact. `superseded`: the next revision of the fact
+     * that held the slot. `replayed`: this call had already written it.
+     */
+    readonly outcome: 'created' | 'superseded' | 'replayed';
+    /** The approval a pending fact waits on. */
+    readonly approvalId?: string;
+}
+/**
+ * Agent memory writes (the `remember` tool). Optional on the agent
+ * bindings: a host without it offers the tool, and a call says it
+ * can't remember.
+ */
+export interface MemoryRememberBinding {
+    remember(input: RememberFactInput): Promise<Result<RememberFactResult, MemoryError>>;
+}
+//# sourceMappingURL=remember.d.ts.map

package/dist/remember.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remember.d.ts","sourceRoot":"","sources":["../src/remember.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAEjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wEAAwE;AACxE,MAAM,MAAM,oBAAoB;AAC9B,+EAA+E;AAC7E,YAAY;AACd,oFAAoF;GAClF,kBAAkB,CAAC;AAEvB;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;IAC1C,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAClE;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;KAC7B,CAAC;IACF,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mEAAmE;IACnE,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,CAAC;IAChC,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,SAAS,oBAAoB,EAAE,CAAA;KAAE,CAAC;CACzE;AAED,MAAM,WAAW,kBAAkB;IACjC,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,iBAAiB,CAAC,CAAC;IACvC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,YAAY,GAAG,UAAU,CAAC;IACxD,4CAA4C;IAC5C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,WAAW,CAAC,CAAC,CAAC;CACtF"}

package/dist/remember.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export {};
+//# sourceMappingURL=remember.js.map

package/dist/remember.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remember.js","sourceRoot":"","sources":["../src/remember.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC"}