@kindgi/memory 0.1.4-rc.5 → 0.1.5-rc.0

package/dist/types.d.ts

@@ -18,7 +18,66 @@ export interface MemoryScope {
     readonly projectId?: ProjectId;
     readonly threadId?: ThreadId;
     readonly sessionId?: SessionId;
+    /**
+     * An app's end user, by the app's own opaque id (as conversations and
+     * judgments name them): a fact about or for one person who isn't a
+     * Kindgi user. A participant's facts are private to that participant's
+     * runs. Needs `projectId`: an app's end users belong to a project.
+     */
+    readonly participantId?: string;
+}
+/**
+ * Who can see which facts: the containers a reader may read, worked out
+ * by the server from the run or the caller (never from a request body),
+ * and applied inside every query. A fact is readable when each container
+ * its scope names is one the reader has: its project, org, user,
+ * participant and thread (a fact naming none of them is tenant-wide, and
+ * every reader in the tenant sees it). A missing field grants none.
+ */
+export interface MemoryReaders {
+    /** Every fact in the tenant (a tenant admin). The other fields are then ignored. */
+    readonly all?: true;
+    /** Projects whose facts it reads. */
+    readonly projectIds?: readonly ProjectId[];
+    /** Orgs whose org-wide facts (no project) it reads: a run's project's org. */
+    readonly orgIds?: readonly OrgId[];
+    /** Kindgi users whose personal facts it reads. */
+    readonly userIds?: readonly UserId[];
+    /** End users (participants) whose facts it reads. */
+    readonly participantIds?: readonly string[];
+    /** Conversations whose thread facts it reads. */
+    readonly threadIds?: readonly ThreadId[];
+    /**
+     * Projects where it reads every participant's and every thread's facts:
+     * an app's own credential, acting for all of its end users.
+     */
+    readonly onBehalfOfProjectIds?: readonly ProjectId[];
+}
+/**
+ * How far a fact is trusted. `verified`: a person with the right checked
+ * it. `asserted`: an app or a person wrote it. `unverified`: an agent
+ * remembered it during a conversation.
+ */
+export type FactTrust = 'verified' | 'asserted' | 'unverified';
+/** Whom a fact is about: what access and erasure requests by person find. */
+export interface FactSubject {
+    readonly kind: 'participant' | 'user' | 'external';
+    readonly id: string;
+}
+/** Who asserted a fact (PROV `wasAttributedTo`), set by the server from the writer. */
+export interface FactAttribution {
+    readonly kind: 'user' | 'service' | 'agent';
+    readonly id: string;
+    readonly agentVersion?: string;
+}
+/** The run step that wrote a fact (PROV `wasGeneratedBy`), for one an agent wrote. */
+export interface FactGeneratedBy {
+    readonly runId: string;
+    readonly stepId?: string;
+    readonly toolCallId?: string;
 }
+/** Why a revision stopped being current. */
+export type FactInvalidationReason = 'superseded' | 'deleted' | 'erased' | 'expired';
 /**
  * Retention override at the fact level. Tenant policy sets defaults; a
  * fact-level override wins if present.
@@ -68,7 +127,13 @@ export interface SourceRefresh {
  * per-fact retrieval hint.
  */
 export interface Fact<TContent = unknown> {
+    /**
+     * The fact, across its revisions: superseding keeps it. (For a fact that
+     * was never superseded it is also its one revision's id.)
+     */
     readonly id: FactId;
+    /** This revision's own id; absent where it equals `id`. */
+    readonly revisionId?: string;
     /**
      * Fact type identifier. Packs define their own; a few general-purpose
      * names are conventional ('working-memory', 'user-profile', 'summary',
@@ -76,7 +141,7 @@ export interface Fact<TContent = unknown> {
      */
     readonly type: string;
     readonly scope: MemoryScope;
-    /** Monotonic version within `(scope, id)`. Supersession increments. */
+    /** The revision number within the fact: 1, then one more per supersede or verify. */
     readonly version: number;
     readonly createdAt: Timestamp;
     readonly updatedAt?: Timestamp;
@@ -92,6 +157,32 @@ export interface Fact<TContent = unknown> {
     readonly retention?: Retention;
     readonly source?: Source;
     readonly causedByLogId?: readonly string[];
+    /** The revision this one replaced (PROV `wasRevisionOf`). */
     readonly supersedes?: FactId;
+    /** How far it's trusted. Absent on facts from before trust was recorded: `asserted`. */
+    readonly trust?: FactTrust;
+    readonly verifiedBy?: string;
+    readonly verifiedAt?: Timestamp;
+    readonly attributedTo?: FactAttribution;
+    readonly generatedBy?: FactGeneratedBy;
+    readonly subjects?: readonly FactSubject[];
+    /** When the fact is true in the world (application time); absent: always. */
+    readonly validFrom?: Timestamp;
+    readonly validUntil?: Timestamp;
+    /** When it was said or seen. */
+    readonly observedAt?: Timestamp;
+    /** When this revision stopped being current (record time), by whom, and why; absent: current. */
+    readonly invalidatedAt?: Timestamp;
+    readonly invalidatedBy?: string;
+    readonly invalidationReason?: FactInvalidationReason;
+    /** `pending` while a person must approve it: a pending fact is never retrieved. */
+    readonly review?: 'pending';
+    /**
+     * When this revision stops being readable: from its retention
+     * (`keepUntil`, or `keepDays` from the fact's first write), or an
+     * agent-remembered fact's unverified window. No read returns it after.
+     * Absent: it doesn't expire.
+     */
+    readonly expiresAt?: Timestamp;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,MAAM,EACN,KAAK,EACL,SAAS,EACT,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,MAAM,EACP,MAAM,eAAe,CAAC;AAEvB;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,UAAU,GAAG,aAAa,GAAG,YAAY,CAAC;IAC/E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;CACjC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,CAAC;IACpC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,GAAG,YAAY,GAAG,QAAQ,CAAC;IACvD;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,IAAI,CAAC,QAAQ,GAAG,OAAO;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindgi/memory",
-  "version": "0.1.4-rc.5",
+  "version": "0.1.5-rc.0",
   "description": "Kindgi™ memory type surface. Public type contract for the memory subsystem: Fact (typed versioned record, Kind-A immutable or Kind-B cached-view), Retention (fact-level retention override), MemoryScope (where in the tenant/user/thread hierarchy a Fact lives), Source + SourceFreshness + SourceRefresh (external-source metadata for Kind-B facts). Also LogEntry + LOG_KINDS (hash-chained run log), RetrievalHit, the MemoryError variants, and MemoryQueryBinding (the data-access interface a binding implementation provides). Types and interfaces only — no runtime state. Storage, indexes, retrieval, and retention sweeps are provided by a binding implementation, such as the Postgres-backed one in the Kindgi runtime.",
   "license": "Apache-2.0",
   "repository": {
@@ -28,8 +28,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@kindgi/embedding": "0.1.4-rc.5",
-    "@kindgi/types": "0.1.4-rc.5"
+    "@kindgi/embedding": "0.1.5-rc.0",
+    "@kindgi/types": "0.1.5-rc.0"
   },
   "engines": {
     "node": ">=22.12.0"
@@ -46,7 +46,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run --typecheck --typecheck.only --passWithNoTests",
+    "test": "vitest run",
     "clean": "rm -rf dist *.tsbuildinfo"
   }
 }

package/src/errors.ts

@@ -22,6 +22,7 @@ export type MemoryError =
   | EmbeddingError
   | RefreshHandlerMissingError
   | RetentionViolationError
+  | ErasureInProgressError
   | PersistenceError;
 
 export interface InvalidLogEntryError {
@@ -69,6 +70,16 @@ export interface RetentionViolationError {
   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/src/fusion.ts

@@ -0,0 +1,50 @@
+// 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;
+
+/** 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 function fuseByRank<T>(
+  legs: Readonly<Record<string, readonly T[]>>,
+  key: (item: T) => string,
+  k: number = RRF_K,
+): readonly Fused<T>[] {
+  const fused = new Map<
+    string,
+    { item: T; score: number; ranks: Record<string, number>; first: number }
+  >();
+  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 }));
+}

package/src/index.ts

@@ -4,6 +4,12 @@
 // ============ Wire types ============
 export type {
   Fact,
+  FactAttribution,
+  FactGeneratedBy,
+  FactInvalidationReason,
+  FactSubject,
+  FactTrust,
+  MemoryReaders,
   MemoryScope,
   Retention,
   Source,
@@ -11,6 +17,23 @@ export type {
   SourceRefresh,
 } from './types.js';
 
+// ============ The scope guard ============
+export { isReadableBy } from './readers.js';
+
+// ============ Recalling earlier conversations ============
+export { isRecallReadableBy } from './recall.js';
+export type {
+  RecallHit,
+  RecallRow,
+  RecallSelection,
+  RecalledMessage,
+  SearchConversationsInput,
+} from './recall.js';
+
+// ============ Hybrid retrieval ============
+export { RRF_K, fuseByRank } from './fusion.js';
+export type { Fused } from './fusion.js';
+
 // ============ Log types ============
 export { LOG_KINDS } from './log.js';
 export type { LogEntry, LogKind } from './log.js';
@@ -20,6 +43,7 @@ export type { RetrievalHit } from './retrieval.js';
 
 // ============ Errors ============
 export type {
+  ErasureInProgressError,
   FactNotFoundError,
   InvalidFactError,
   InvalidLogEntryError,
@@ -30,6 +54,15 @@ export type {
   RetentionViolationError,
 } from './errors.js';
 
+// ============ Agent memory writes (the `remember` tool) ============
+export type {
+  MemoryRememberBinding,
+  RememberFactInput,
+  RememberFactResult,
+  RememberReviewReason,
+  RememberedContent,
+} from './remember.js';
+
 // ============ MemoryQueryBinding — caller-plugged data-access surface ============
 export type {
   AppendLogInput,

package/src/log.ts

@@ -48,4 +48,18 @@ 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;
 }

package/src/memory-binding.ts

@@ -7,10 +7,12 @@ import type {
   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
@@ -32,7 +34,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,
@@ -56,6 +60,19 @@ export interface MemoryQueryBinding {
     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`).
+   * 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
@@ -75,8 +92,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;
 }
 
@@ -85,6 +109,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;
 }
 
@@ -99,6 +128,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;
 }
 

package/src/readers.ts

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+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 function isReadableBy(scope: MemoryScope, readers: MemoryReaders): boolean {
+  if (readers.all === true) return true;
+  const project = scope.projectId;
+  const has = <T>(ids: readonly T[] | undefined, id: T) => 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;
+}

package/src/recall.ts

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+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 function isRecallReadableBy(row: RecallRow, readers: MemoryReaders): boolean {
+  if (readers.all === true) return true;
+  const has = <T>(ids: readonly T[] | undefined, id: T | undefined) =>
+    id !== undefined && ids?.includes(id) === true;
+  const project = row.projectId;
+  const onBehalf = has(readers.onBehalfOfProjectIds as readonly string[] | undefined, project);
+  if (
+    project !== undefined &&
+    !(has(readers.projectIds as readonly string[] | undefined, project) || onBehalf)
+  ) {
+    return false;
+  }
+  const isPerson =
+    row.participantId !== undefined
+      ? has(readers.participantIds, row.participantId)
+      : has(readers.userIds as readonly string[] | undefined, row.userId);
+  return (
+    isPerson ||
+    has(readers.threadIds as readonly string[] | undefined, row.conversationId) ||
+    onBehalf
+  );
+}

package/src/remember.ts

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+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>>;
+}