@fgv/ts-agent-memory 5.1.0-36

package/src/packlets/retrieve/retriever.ts

@@ -0,0 +1,207 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Result, fail, succeed } from '@fgv/ts-utils';
+import { IMemoryRecord, Kind, MemoryId, MemoryScopeKey, Tag } from '../types';
+import { IIndexedMemoryRecord } from '../index';
+
+/**
+ * The capabilities a retriever exposes. A consumer probes these before
+ * dispatching a query so it never silently gets an empty result for a
+ * capability the retriever does not implement.
+ * @public
+ */
+export interface IMemoryRetrieverCapabilities {
+  /** Semantic / vector recall is operational (an {@link IVectorIndex} is wired). */
+  readonly supportsSemanticRecall: boolean;
+  /** Temporal "as-of" queries are operational (a temporal index is wired). */
+  readonly supportsTemporalQuery: boolean;
+  /** Link traversal is supported (an in-memory backlink index is present). */
+  readonly supportsLinkTraversal: boolean;
+}
+
+/**
+ * A retrieval query. Every field is optional; an empty query is the "recency
+ * over everything" request. `semantic` and `asOf` are present from day one (the
+ * no-resignature guarantee): a backend that adds semantic or temporal recall
+ * sets the matching capability flag, with no interface change.
+ * @public
+ */
+export interface IMemoryQuery {
+  /** Restrict to records in this scope. */
+  readonly scope?: MemoryScopeKey;
+  /** Restrict to records carrying this tag (exact match). */
+  readonly tag?: Tag;
+  /** Restrict to records of this kind. */
+  readonly kind?: Kind;
+  /** Restrict to records linked FROM this id (outbound). */
+  readonly linkedFrom?: MemoryId;
+  /** Restrict to records linked TO this id (inbound / backlinks). */
+  readonly linkedTo?: MemoryId;
+  /** BFS hop count for link traversal. Default: 1. */
+  readonly hops?: number;
+  /**
+   * Text query for semantic / vector recall. If set and the retriever's
+   * `supportsSemanticRecall` is `false`, the retriever returns a loud
+   * `Result.fail` ({@link SEMANTIC_UNWIRED_MESSAGE}) — never a silent empty.
+   */
+  readonly semantic?: string;
+  /** Top-K for semantic recall. Default: 10. */
+  readonly topK?: number;
+  /**
+   * As-of epoch ms for temporal "valid at" queries. If set and the retriever's
+   * `supportsTemporalQuery` is `false`, the retriever returns a loud
+   * `Result.fail` — never a silent empty.
+   */
+  readonly asOf?: number;
+  /** Maximum records to return. Applied after all other filters. */
+  readonly limit?: number;
+  /** Arbitrary predicate applied after the scope / kind / tag pre-filter. */
+  readonly filter?: (record: IMemoryRecord<unknown>) => boolean;
+}
+
+/**
+ * The retrieval contract. A retriever exposes its {@link
+ * IMemoryRetrieverCapabilities | capabilities} and answers
+ * {@link IMemoryRetriever.retrieve | queries}, degrading loudly (never silently
+ * empty) when a requested capability is not wired.
+ * @public
+ */
+export interface IMemoryRetriever {
+  /** The capabilities this retriever exposes. Probe before dispatch. */
+  readonly capabilities: IMemoryRetrieverCapabilities;
+  /**
+   * Retrieve records matching `query`. Returns a `Result.fail` with a
+   * diagnostic message when the query requests a capability this retriever does
+   * not support (never an empty success).
+   */
+  retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+}
+
+/**
+ * The loud-degradation message a retriever returns when `query.semantic` is set
+ * but no {@link IVectorIndex} is wired.
+ * @public
+ */
+export const SEMANTIC_UNWIRED_MESSAGE: string = 'semantic recall requires a vector index; none configured';
+
+/**
+ * The loud-degradation message a retriever returns when a link-traversal axis
+ * (`linkedFrom` / `linkedTo` / `hops`) is requested but no backlink index is
+ * wired.
+ * @public
+ */
+export const LINK_TRAVERSAL_UNWIRED_MESSAGE: string =
+  'link traversal requires a backlink index; none configured';
+
+/**
+ * The capabilities every non-semantic, non-temporal, non-link v1 retriever
+ * exposes (all three flags `false`).
+ * @public
+ */
+export const NON_SEMANTIC_CAPABILITIES: IMemoryRetrieverCapabilities = {
+  supportsSemanticRecall: false,
+  supportsTemporalQuery: false,
+  supportsLinkTraversal: false
+};
+
+/**
+ * Build the loud-degradation message a retriever returns when `query.asOf` is
+ * set but no temporal index is wired.
+ * @public
+ */
+export function temporalUnwiredMessage(kind?: Kind): string {
+  return `temporal query requires temporal index; none configured${
+    kind !== undefined ? ` for kind ${kind}` : ''
+  }`;
+}
+
+/**
+ * Enforce the loud-degradation contract for the `semantic` and `asOf` axes
+ * against a retriever's `capabilities`: a requested capability the retriever
+ * does not support fails loudly rather than returning a silent empty result.
+ * @public
+ */
+export function guardRetrieverCapabilities(
+  query: IMemoryQuery,
+  capabilities: IMemoryRetrieverCapabilities
+): Result<true> {
+  if (query.semantic !== undefined && !capabilities.supportsSemanticRecall) {
+    return fail(SEMANTIC_UNWIRED_MESSAGE);
+  }
+  if (query.asOf !== undefined && !capabilities.supportsTemporalQuery) {
+    return fail(temporalUnwiredMessage(query.kind));
+  }
+  const requestsLinkTraversal: boolean =
+    query.linkedFrom !== undefined || query.linkedTo !== undefined || query.hops !== undefined;
+  if (requestsLinkTraversal && !capabilities.supportsLinkTraversal) {
+    return fail(LINK_TRAVERSAL_UNWIRED_MESSAGE);
+  }
+  return succeed(true);
+}
+
+/**
+ * Recency comparator: most-recently-updated first, with a `seq` tiebreak so
+ * equal-`updated` records sort deterministically. Mirrors the B1 index ordering.
+ * @public
+ */
+export function recencyCompare(a: IMemoryRecord<unknown>, b: IMemoryRecord<unknown>): number {
+  const byUpdated: number = b.envelope.updated - a.envelope.updated;
+  return byUpdated !== 0 ? byUpdated : b.envelope.seq - a.envelope.seq;
+}
+
+/**
+ * Whether an indexed entry satisfies a query's scope / kind / tag / predicate
+ * pre-filter (the axes shared by every v1 retriever). The `semantic` / `asOf` /
+ * link axes are NOT applied here — those are each retriever's own concern.
+ * @public
+ */
+export function indexedRecordMatchesQuery(entry: IIndexedMemoryRecord, query: IMemoryQuery): boolean {
+  if (query.scope !== undefined && entry.scope !== query.scope) {
+    return false;
+  }
+  if (query.kind !== undefined && entry.record.envelope.kind !== query.kind) {
+    return false;
+  }
+  if (query.tag !== undefined && !entry.record.envelope.tags.includes(query.tag)) {
+    return false;
+  }
+  if (query.filter !== undefined && !query.filter(entry.record)) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Apply the shared scope / kind / tag / predicate pre-filter to a set of indexed
+ * entries, returning the surviving records (unordered, unlimited).
+ * @public
+ */
+export function selectByQuery(
+  entries: ReadonlyArray<IIndexedMemoryRecord>,
+  query: IMemoryQuery
+): IMemoryRecord<unknown>[] {
+  return entries.filter((entry) => indexedRecordMatchesQuery(entry, query)).map((entry) => entry.record);
+}
+
+/**
+ * Truncate to `query.limit` records (a no-op when `limit` is absent). Applied
+ * last, after ordering, so it always takes the top-N of the ordered result. A
+ * non-positive `limit` is public query input and means "no records" — it returns
+ * an empty array rather than letting a negative value slip into `slice`.
+ * @public
+ */
+export function limitRecords(
+  records: ReadonlyArray<IMemoryRecord<unknown>>,
+  limit?: number
+): ReadonlyArray<IMemoryRecord<unknown>> {
+  if (limit === undefined) {
+    return records;
+  }
+  if (limit <= 0) {
+    return [];
+  }
+  return records.length > limit ? records.slice(0, limit) : records;
+}

package/src/packlets/retrieve/semanticRetriever.ts

@@ -0,0 +1,147 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Result, fail, succeed } from '@fgv/ts-utils';
+import { IMemoryRecord, MemoryId } from '../types';
+import { IIndexedMemoryRecord, IMemoryIndex } from '../index';
+import { IVectorIndex, IVectorQueryHit } from '../vector';
+import {
+  IMemoryQuery,
+  IMemoryRetriever,
+  IMemoryRetrieverCapabilities,
+  SEMANTIC_UNWIRED_MESSAGE,
+  indexedRecordMatchesQuery,
+  limitRecords,
+  temporalUnwiredMessage
+} from './retriever';
+
+/**
+ * Embeds a query string into a vector for {@link IVectorIndex.query}. Async and
+ * `Result`-returning, since a real embedder does a network call.
+ * @public
+ */
+export type QueryEmbedder = (text: string) => Promise<Result<Float32Array>>;
+
+/**
+ * The semantic backend wired into a {@link SemanticRetriever}: the vector index
+ * to query and the embedder that turns the query text into a vector. Both are
+ * required together — a vector index is useless without a way to embed the
+ * query, so {@link SemanticRetriever.create} treats them as one unit.
+ * @public
+ */
+export interface ISemanticBackend {
+  /** The vector index to query. */
+  readonly vectorIndex: IVectorIndex;
+  /** Turns the query text into a vector. */
+  readonly embedQuery: QueryEmbedder;
+}
+
+/**
+ * Construction options for {@link SemanticRetriever.create}.
+ * @public
+ */
+export interface ISemanticRetrieverCreateParams {
+  /** The record index, used to resolve vector hits back to full records. */
+  readonly index: IMemoryIndex;
+  /**
+   * The semantic backend. When absent, the retriever reports
+   * `supportsSemanticRecall: false` and a `query.semantic` request degrades
+   * loudly ({@link SEMANTIC_UNWIRED_MESSAGE}) rather than returning empty.
+   */
+  readonly backend?: ISemanticBackend;
+}
+
+/**
+ * Vector-recall retriever. When a {@link ISemanticBackend | backend} is wired it
+ * embeds `query.semantic`, queries the vector index, and resolves the hits back
+ * to records (preserving vector score order). When no backend is wired,
+ * `supportsSemanticRecall` is `false` and any `query.semantic` request degrades
+ * loudly — it NEVER returns a silent empty.
+ *
+ * @remarks
+ * A consumer-supplied backend that rejects (throws) is normalized into a
+ * `Failure` — `retrieve` always honors its `Promise<Result<...>>` contract.
+ * @public
+ */
+export class SemanticRetriever implements IMemoryRetriever {
+  private readonly _index: IMemoryIndex;
+  private readonly _backend: ISemanticBackend | undefined;
+
+  private constructor(index: IMemoryIndex, backend: ISemanticBackend | undefined) {
+    this._index = index;
+    this._backend = backend;
+  }
+
+  /** {@inheritDoc IMemoryRetriever.capabilities} */
+  public get capabilities(): IMemoryRetrieverCapabilities {
+    return {
+      supportsSemanticRecall: this._backend !== undefined,
+      supportsTemporalQuery: false,
+      supportsLinkTraversal: false
+    };
+  }
+
+  /** Family-convention factory. */
+  public static create(params: ISemanticRetrieverCreateParams): Result<SemanticRetriever> {
+    return succeed(new SemanticRetriever(params.index, params.backend));
+  }
+
+  /** {@inheritDoc IMemoryRetriever.retrieve} */
+  public async retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>> {
+    if (query.asOf !== undefined) {
+      return fail(temporalUnwiredMessage(query.kind));
+    }
+    if (query.semantic === undefined) {
+      // The semantic term is this retriever's axis; without it there is nothing
+      // to recall (a no-op contribution to a HybridRetriever, not a failure).
+      return succeed([]);
+    }
+    if (this._backend === undefined) {
+      return fail(SEMANTIC_UNWIRED_MESSAGE);
+    }
+    const backend: ISemanticBackend = this._backend;
+    // The backend hooks are consumer-supplied; a rejecting (throwing) impl must
+    // still surface as a `Failure`, never escape `retrieve` as a rejected
+    // promise. `_callBackend` normalizes both a returned `fail` and a rejection.
+    const embedded: Result<Float32Array> = await SemanticRetriever._callBackend('query embedding', () =>
+      backend.embedQuery(query.semantic as string)
+    );
+    if (embedded.isFailure()) {
+      return fail(embedded.message);
+    }
+    const hits: Result<ReadonlyArray<IVectorQueryHit>> = await SemanticRetriever._callBackend(
+      'vector query',
+      () => backend.vectorIndex.query(embedded.value, query.topK ?? 10)
+    );
+    if (hits.isFailure()) {
+      return fail(hits.message);
+    }
+    const byId: Map<MemoryId, IIndexedMemoryRecord> = new Map(
+      this._index.entries().map((entry) => [entry.record.envelope.id, entry])
+    );
+    const records: IMemoryRecord<unknown>[] = [];
+    for (const hit of hits.value) {
+      const entry: IIndexedMemoryRecord | undefined = byId.get(hit.id);
+      if (entry !== undefined && indexedRecordMatchesQuery(entry, query)) {
+        records.push(entry.record);
+      }
+    }
+    return succeed(limitRecords(records, query.limit));
+  }
+
+  /**
+   * Invoke a consumer-supplied backend hook, normalizing both a returned `fail`
+   * and a thrown/rejected promise into a single `semantic recall: <label> failed`
+   * `Failure`. Keeps `retrieve` within the `Promise<Result<...>>` contract even
+   * when the injected `embedQuery` / `vectorIndex` misbehaves.
+   */
+  private static async _callBackend<T>(label: string, op: () => Promise<Result<T>>): Promise<Result<T>> {
+    try {
+      return (await op()).withErrorFormat((msg) => `semantic recall: ${label} failed: ${msg}`);
+    } catch (err) {
+      return fail(`semantic recall: ${label} failed: ${String(err)}`);
+    }
+  }
+}

package/src/packlets/retrieve/structuredFilterRetriever.ts

@@ -0,0 +1,58 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Result, succeed } from '@fgv/ts-utils';
+import { IMemoryRecord } from '../types';
+import { IMemoryIndex } from '../index';
+import {
+  IMemoryQuery,
+  IMemoryRetriever,
+  IMemoryRetrieverCapabilities,
+  NON_SEMANTIC_CAPABILITIES,
+  guardRetrieverCapabilities,
+  limitRecords,
+  recencyCompare,
+  selectByQuery
+} from './retriever';
+
+/**
+ * Returns records matching `query.filter`, narrowed by any scope / kind / tag
+ * pre-filter and recency-ordered. The predicate is this retriever's axis: a
+ * query without a `filter` is not its concern and yields an empty success (so it
+ * contributes nothing to a {@link HybridRetriever}, rather than failing).
+ * @public
+ */
+export class StructuredFilterRetriever implements IMemoryRetriever {
+  private readonly _index: IMemoryIndex;
+
+  private constructor(index: IMemoryIndex) {
+    this._index = index;
+  }
+
+  /** {@inheritDoc IMemoryRetriever.capabilities} */
+  public get capabilities(): IMemoryRetrieverCapabilities {
+    return NON_SEMANTIC_CAPABILITIES;
+  }
+
+  /** Family-convention factory. */
+  public static create(index: IMemoryIndex): Result<StructuredFilterRetriever> {
+    return succeed(new StructuredFilterRetriever(index));
+  }
+
+  /** {@inheritDoc IMemoryRetriever.retrieve} */
+  public retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>> {
+    return Promise.resolve(
+      guardRetrieverCapabilities(query, this.capabilities).onSuccess(() => {
+        if (query.filter === undefined) {
+          return succeed([]);
+        }
+        const ordered: IMemoryRecord<unknown>[] = selectByQuery(this._index.entries(), query).sort(
+          recencyCompare
+        );
+        return succeed(limitRecords(ordered, query.limit));
+      })
+    );
+  }
+}

package/src/packlets/retrieve/tagRetriever.ts

@@ -0,0 +1,58 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Result, succeed } from '@fgv/ts-utils';
+import { IMemoryRecord } from '../types';
+import { IMemoryIndex } from '../index';
+import {
+  IMemoryQuery,
+  IMemoryRetriever,
+  IMemoryRetrieverCapabilities,
+  NON_SEMANTIC_CAPABILITIES,
+  guardRetrieverCapabilities,
+  limitRecords,
+  recencyCompare,
+  selectByQuery
+} from './retriever';
+
+/**
+ * Returns records carrying `query.tag`, recency-ordered within the tag and
+ * narrowed by any scope / kind / predicate filters. Tag is this retriever's
+ * axis: a query without a `tag` is not its concern and yields an empty success
+ * (so it contributes nothing to a {@link HybridRetriever}, rather than failing).
+ * @public
+ */
+export class TagRetriever implements IMemoryRetriever {
+  private readonly _index: IMemoryIndex;
+
+  private constructor(index: IMemoryIndex) {
+    this._index = index;
+  }
+
+  /** {@inheritDoc IMemoryRetriever.capabilities} */
+  public get capabilities(): IMemoryRetrieverCapabilities {
+    return NON_SEMANTIC_CAPABILITIES;
+  }
+
+  /** Family-convention factory. */
+  public static create(index: IMemoryIndex): Result<TagRetriever> {
+    return succeed(new TagRetriever(index));
+  }
+
+  /** {@inheritDoc IMemoryRetriever.retrieve} */
+  public retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>> {
+    return Promise.resolve(
+      guardRetrieverCapabilities(query, this.capabilities).onSuccess(() => {
+        if (query.tag === undefined) {
+          return succeed([]);
+        }
+        const ordered: IMemoryRecord<unknown>[] = selectByQuery(this._index.entries(), query).sort(
+          recencyCompare
+        );
+        return succeed(limitRecords(ordered, query.limit));
+      })
+    );
+  }
+}