@fgv/ts-agent-memory 5.1.0-36

package/src/packlets/observe/observer.ts

@@ -0,0 +1,119 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Result } from '@fgv/ts-utils';
+import { IProvenance, Kind, MemoryId, MemoryScopeKey } from '../types';
+
+/**
+ * The store/retriever operation an observation record describes.
+ *
+ * @remarks
+ * `'read'` / `'write'` / `'delete'` are fired post-op by
+ * {@link FileTreeMemoryStore} (on `get` / `put` / `delete` respectively) when
+ * observers are wired. `'retrieve'` is reserved for retriever-fired
+ * observations; no B2 retriever fires one (a single seq authority per
+ * observation store is the supported topology), so it never appears in B2 but
+ * is part of the vocabulary so a future retriever-firing hook is additive.
+ * @public
+ */
+export type MemoryObservationPhase = 'read' | 'write' | 'delete' | 'retrieve';
+
+/**
+ * The outcome of the observed operation.
+ * @public
+ */
+export type MemoryObservationOutcome = 'success' | 'failure';
+
+/**
+ * A single audit record produced by an observed store (or retriever) operation.
+ *
+ * @remarks
+ * `seq` and `timestamp` are assigned by the firing authority (the store) before
+ * fan-out, so the same record carries the same `seq` across every observer it
+ * lands in. `seq` is strictly increasing per authority, satisfying the
+ * `RetainingRingBuffer` cursor contract that {@link MemoryObservationStore}
+ * relies on.
+ * @public
+ */
+export interface IMemoryObservationRecord {
+  /**
+   * Monotonic 1-based sequence number assigned by the firing authority, stable
+   * across a store's ring eviction. The ordering / paging key.
+   */
+  readonly seq: number;
+  /** Milliseconds since epoch when the firing authority produced the record. */
+  readonly timestamp: number;
+  /** Which operation this record describes. */
+  readonly phase: MemoryObservationPhase;
+  /** The scope the operation touched, when resolvable. */
+  readonly scope?: MemoryScopeKey;
+  /** The record id the operation touched, when resolvable. */
+  readonly id?: MemoryId;
+  /** The kind the operation targeted, when known. */
+  readonly kind?: Kind;
+  /** Whether the operation succeeded. */
+  readonly outcome: MemoryObservationOutcome;
+  /** Present on failure: the failure `Result`'s message. */
+  readonly error?: string;
+  /** Structured provenance of the write, when the operation carried one. */
+  readonly provenance?: IProvenance;
+  /**
+   * For `'retrieve'` observations: an opaque snapshot of the query that drove
+   * the retrieval. Carried verbatim; never interpreted by the store.
+   */
+  readonly querySnapshot?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Single-method async observer hook. The store fires `observe` once per public
+ * `get` / `put` / `delete` call when observers are wired.
+ *
+ * @remarks
+ * Observer errors never affect the store operation — the store swallows a
+ * failed `Result` or a thrown / rejected `observe`, logging it to the injected
+ * diagnostic logger at `warn`.
+ * @public
+ */
+export interface IMemoryObserver {
+  /**
+   * When `true`, the store dispatches `observe` without awaiting it, so a slow
+   * remote observer (SIEM, network sink) does not extend the store operation's
+   * latency. Defaults to `false` (awaited), which is correct for the cheap
+   * in-memory default {@link MemoryObservationStore}. Errors are swallowed
+   * either way.
+   */
+  readonly fireAndForget?: boolean;
+  /**
+   * Receives a fully-formed observation record.
+   * @param record - The observation record.
+   * @returns A `Result` whose failure is swallowed (logged to the store's
+   * diagnostic logger). A rejected promise is likewise swallowed.
+   */
+  observe(record: IMemoryObservationRecord): Promise<Result<unknown>>;
+}
+
+/**
+ * Query criteria for {@link MemoryObservationStore.query}. All supplied criteria
+ * are AND-combined.
+ * @public
+ */
+export interface IMemoryObservationQuery {
+  /** Only records with `seq > sinceSeq` (incremental paging cursor). */
+  readonly sinceSeq?: number;
+  /** Return at most this many records — the most-recent N, still oldest-first. */
+  readonly limit?: number;
+  /** Only records with `timestamp >= since`. */
+  readonly since?: number;
+  /** Only records with `timestamp <= until`. */
+  readonly until?: number;
+  /** Only records that touched this scope. */
+  readonly scope?: MemoryScopeKey;
+  /** Only records that targeted this kind. */
+  readonly kind?: Kind;
+  /** Only records of this phase. */
+  readonly phase?: MemoryObservationPhase;
+  /** Only records with this outcome. */
+  readonly outcome?: MemoryObservationOutcome;
+}

package/src/packlets/retrieve/hybridRetriever.ts

@@ -0,0 +1,181 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Result, fail, mapResults, succeed } from '@fgv/ts-utils';
+import { IMemoryRecord, MemoryId } from '../types';
+import {
+  IMemoryQuery,
+  IMemoryRetriever,
+  IMemoryRetrieverCapabilities,
+  guardRetrieverCapabilities,
+  limitRecords,
+  recencyCompare
+} from './retriever';
+
+/**
+ * Strategy for combining the result sets of the retrievers a
+ * {@link HybridRetriever} composes. Injectable so a consumer can weight,
+ * re-rank, or intersect instead of the default union.
+ * @public
+ */
+export interface IMergeStrategy {
+  /**
+   * Merge the per-retriever result sets into a single ordered result.
+   * @param resultSets - One entry per composed retriever, in composition order.
+   */
+  merge(
+    resultSets: ReadonlyArray<ReadonlyArray<IMemoryRecord<unknown>>>
+  ): Result<ReadonlyArray<IMemoryRecord<unknown>>>;
+}
+
+/**
+ * The reference {@link IMergeStrategy}: a score-union. Every record is scored by
+ * the number of composed result sets it appears in (deduplicated by
+ * {@link IMemoryEnvelope.id | id}); the merged result is ordered by descending
+ * score, then by recency. Records surfaced by more retrievers rank higher.
+ *
+ * @remarks
+ * Dedup is by `id` alone, which is unambiguous for the flat (one-file-per-entity)
+ * kinds B2 ships. Phase-C versioned kinds that reuse a stem across scopes will
+ * extend the dedup key — additive, no API change.
+ * @public
+ */
+export class ScoreUnionMergeStrategy implements IMergeStrategy {
+  private constructor() {}
+
+  /** Family-convention factory. */
+  public static create(): Result<ScoreUnionMergeStrategy> {
+    return succeed(new ScoreUnionMergeStrategy());
+  }
+
+  /** {@inheritDoc IMergeStrategy.merge} */
+  public merge(
+    resultSets: ReadonlyArray<ReadonlyArray<IMemoryRecord<unknown>>>
+  ): Result<ReadonlyArray<IMemoryRecord<unknown>>> {
+    const scored: Map<MemoryId, { readonly record: IMemoryRecord<unknown>; score: number }> = new Map();
+    for (const set of resultSets) {
+      // Count each id at most once per result set, so the score is "how many
+      // retrievers surfaced this record" rather than "how many copies total".
+      const seenInSet: Set<MemoryId> = new Set<MemoryId>();
+      for (const record of set) {
+        const id: MemoryId = record.envelope.id;
+        if (seenInSet.has(id)) {
+          continue;
+        }
+        seenInSet.add(id);
+        const existing = scored.get(id);
+        if (existing === undefined) {
+          scored.set(id, { record, score: 1 });
+        } else {
+          existing.score += 1;
+        }
+      }
+    }
+    const merged: IMemoryRecord<unknown>[] = Array.from(scored.values())
+      .sort((a, b) => (b.score !== a.score ? b.score - a.score : recencyCompare(a.record, b.record)))
+      .map((entry) => entry.record);
+    return succeed(merged);
+  }
+}
+
+/**
+ * Composes several retrievers, dispatches a query to each, and merges their
+ * results via an injectable {@link IMergeStrategy}. Its capabilities are the
+ * union of the composed retrievers' capabilities.
+ *
+ * @remarks
+ * The hybrid enforces the loud-degradation contract against its OWN (union)
+ * capabilities, then projects the query for each child: a child that does not
+ * support the `semantic` (or `asOf`) axis is handed a query with that axis
+ * stripped, so it returns its normal results instead of loud-failing on a field
+ * a sibling handles. A child that genuinely fails (e.g. a wired semantic backend
+ * erroring) propagates — the hybrid never silently drops a failure.
+ * @public
+ */
+export class HybridRetriever implements IMemoryRetriever {
+  private readonly _retrievers: ReadonlyArray<IMemoryRetriever>;
+  private readonly _mergeStrategy: IMergeStrategy;
+  private readonly _capabilities: IMemoryRetrieverCapabilities;
+
+  private constructor(
+    retrievers: ReadonlyArray<IMemoryRetriever>,
+    mergeStrategy: IMergeStrategy,
+    capabilities: IMemoryRetrieverCapabilities
+  ) {
+    this._retrievers = retrievers;
+    this._mergeStrategy = mergeStrategy;
+    this._capabilities = capabilities;
+  }
+
+  /** {@inheritDoc IMemoryRetriever.capabilities} */
+  public get capabilities(): IMemoryRetrieverCapabilities {
+    return this._capabilities;
+  }
+
+  /**
+   * Family-convention factory.
+   * @param retrievers - The retrievers to compose (at least one).
+   * @param mergeStrategy - How to combine their results.
+   */
+  public static create(
+    retrievers: ReadonlyArray<IMemoryRetriever>,
+    mergeStrategy: IMergeStrategy
+  ): Result<HybridRetriever> {
+    if (retrievers.length === 0) {
+      return fail('HybridRetriever: at least one retriever is required');
+    }
+    // Snapshot the caller's array so a later mutation cannot make `retrieve()`
+    // and the cached `capabilities` disagree.
+    const stableRetrievers: ReadonlyArray<IMemoryRetriever> = [...retrievers];
+    const capabilities: IMemoryRetrieverCapabilities = {
+      supportsSemanticRecall: stableRetrievers.some((r) => r.capabilities.supportsSemanticRecall),
+      supportsTemporalQuery: stableRetrievers.some((r) => r.capabilities.supportsTemporalQuery),
+      supportsLinkTraversal: stableRetrievers.some((r) => r.capabilities.supportsLinkTraversal)
+    };
+    return succeed(new HybridRetriever(stableRetrievers, mergeStrategy, capabilities));
+  }
+
+  /** {@inheritDoc IMemoryRetriever.retrieve} */
+  public async retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>> {
+    return guardRetrieverCapabilities(query, this._capabilities).thenOnSuccess(async () => {
+      const perRetriever: Result<ReadonlyArray<IMemoryRecord<unknown>>>[] = await Promise.all(
+        this._retrievers.map((retriever) => retriever.retrieve(this._projectQuery(query, retriever)))
+      );
+      return mapResults(perRetriever)
+        .onSuccess((resultSets) => this._mergeStrategy.merge(resultSets))
+        .onSuccess((merged) => succeed(limitRecords(merged, query.limit)));
+    });
+  }
+
+  /**
+   * Project the query for one child retriever. Two adjustments:
+   *
+   * - Strip axes the child does not support (`semantic` / `topK` for a
+   *   non-semantic child, `asOf` for a non-temporal child, the link axes for a
+   *   non-link child) so it returns its normal results rather than loud-failing
+   *   on a field a sibling handles.
+   * - Strip `limit` unconditionally: limit is a post-merge concern. A child that
+   *   pre-truncated its result set would starve the merge strategy of candidates
+   *   it needs to score correctly (a record both children would surface must
+   *   reach the merge to score 2). The hybrid applies `limit` once, after merge.
+   */
+  private _projectQuery(query: IMemoryQuery, retriever: IMemoryRetriever): IMemoryQuery {
+    const projected: { -readonly [K in keyof IMemoryQuery]: IMemoryQuery[K] } = { ...query };
+    delete projected.limit;
+    if (!retriever.capabilities.supportsSemanticRecall) {
+      delete projected.semantic;
+      delete projected.topK;
+    }
+    if (!retriever.capabilities.supportsTemporalQuery) {
+      delete projected.asOf;
+    }
+    if (!retriever.capabilities.supportsLinkTraversal) {
+      delete projected.linkedFrom;
+      delete projected.linkedTo;
+      delete projected.hops;
+    }
+    return projected;
+  }
+}

package/src/packlets/retrieve/index.ts

@@ -0,0 +1,12 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './retriever';
+export * from './recencyRetriever';
+export * from './linkTraversalRetriever';
+export * from './tagRetriever';
+export * from './structuredFilterRetriever';
+export * from './semanticRetriever';
+export * from './hybridRetriever';

package/src/packlets/retrieve/linkTraversalRetriever.ts

@@ -0,0 +1,169 @@
+/*
+ * 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 {
+  IMemoryQuery,
+  IMemoryRetriever,
+  IMemoryRetrieverCapabilities,
+  guardRetrieverCapabilities,
+  indexedRecordMatchesQuery,
+  limitRecords,
+  recencyCompare
+} from './retriever';
+
+/** The capabilities a link-traversal retriever exposes (link traversal only). */
+const LINK_TRAVERSAL_CAPABILITIES: IMemoryRetrieverCapabilities = {
+  supportsSemanticRecall: false,
+  supportsTemporalQuery: false,
+  supportsLinkTraversal: true
+};
+
+/** Default BFS hop count when `query.hops` is not supplied. */
+const DEFAULT_HOPS: number = 1;
+
+/**
+ * The loud-degradation message returned when a link-traversal query supplies no
+ * seed (`linkedFrom` / `linkedTo`).
+ * @public
+ */
+export const LINK_TRAVERSAL_NO_SEED_MESSAGE: string =
+  'link traversal requires a seed id (linkedFrom or linkedTo)';
+
+/**
+ * Breadth-first link-traversal retriever. From a seed {@link MemoryId} it walks
+ * the link graph up to `query.hops` levels and returns the records reached
+ * (excluding the seed), recency-ordered and limited.
+ *
+ * @remarks
+ * - **Direction.** `linkedFrom` walks OUTBOUND edges (each record's
+ *   `envelope.links[].target`); `linkedTo` walks INBOUND edges (the index's
+ *   `backlinks`). Exactly one is the seed; `linkedFrom` wins if both are set.
+ * - **Bound + cycle safety.** Traversal is bounded by `hops` (default `1` — a
+ *   single hop) and a visited-set guard. The graph is keyed by bare
+ *   string {@link MemoryId}s, so a `Set<string>` visited-set is the exact,
+ *   collision-free cycle key — no structural hashing (e.g. `Crc32Normalizer`) is
+ *   needed. A self-loop or any multi-hop cycle terminates because a revisited id
+ *   is never re-expanded.
+ * - **Post-filter.** The scope / kind / tag / predicate axes of the query are
+ *   applied to the reached records (the link axes are the traversal itself).
+ * @public
+ */
+export class LinkTraversalRetriever implements IMemoryRetriever {
+  private readonly _index: IMemoryIndex;
+
+  private constructor(index: IMemoryIndex) {
+    this._index = index;
+  }
+
+  /** Family-convention factory. */
+  public static create(index: IMemoryIndex): Result<LinkTraversalRetriever> {
+    return succeed(new LinkTraversalRetriever(index));
+  }
+
+  /** {@inheritDoc IMemoryRetriever.capabilities} */
+  public get capabilities(): IMemoryRetrieverCapabilities {
+    return LINK_TRAVERSAL_CAPABILITIES;
+  }
+
+  /** {@inheritDoc IMemoryRetriever.retrieve} */
+  public retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>> {
+    return Promise.resolve(
+      guardRetrieverCapabilities(query, this.capabilities).onSuccess(() => this._traverse(query))
+    );
+  }
+
+  /** Run the bounded, cycle-safe BFS and post-filter the reached records. */
+  private _traverse(query: IMemoryQuery): Result<ReadonlyArray<IMemoryRecord<unknown>>> {
+    const outbound: boolean = query.linkedFrom !== undefined;
+    const seed: MemoryId | undefined = query.linkedFrom ?? query.linkedTo;
+    if (seed === undefined) {
+      return fail(LINK_TRAVERSAL_NO_SEED_MESSAGE);
+    }
+    const hops: number = query.hops ?? DEFAULT_HOPS;
+    const byId: ReadonlyMap<MemoryId, IIndexedMemoryRecord[]> = this._indexById();
+
+    // The visited-set IS the cycle guard: ids are strings, so set membership is
+    // an exact identity check. The seed is pre-marked so it is never re-added.
+    const visited: Set<string> = new Set<string>([seed]);
+    const reached: MemoryId[] = [];
+    let frontier: MemoryId[] = [seed];
+    for (let hop = 0; hop < hops && frontier.length > 0; hop++) {
+      const next: MemoryId[] = [];
+      for (const id of frontier) {
+        for (const neighbor of outbound ? this._outbound(id, byId) : this._inbound(id)) {
+          if (!visited.has(neighbor)) {
+            visited.add(neighbor);
+            reached.push(neighbor);
+            next.push(neighbor);
+          }
+        }
+      }
+      frontier = next;
+    }
+
+    const entries: IIndexedMemoryRecord[] = [];
+    for (const id of reached) {
+      const matches: IIndexedMemoryRecord[] | undefined = byId.get(id);
+      if (matches !== undefined) {
+        entries.push(...matches);
+      }
+    }
+    const ordered: IMemoryRecord<unknown>[] = entries
+      .filter((entry) => indexedRecordMatchesQuery(entry, query))
+      .map((entry) => entry.record)
+      .sort(recencyCompare);
+    return succeed(limitRecords(ordered, query.limit));
+  }
+
+  /**
+   * Group the index's entries by bare {@link MemoryId}. An id can map to more
+   * than one entry when distinct scopes reuse a filename stem (e.g. `turn-0` in
+   * two conversations), so the value is an array.
+   *
+   * @remarks
+   * **Design note (links are globally-scoped identifiers in this phase).** An
+   * {@link IEdge.target} is a bare `MemoryId`, not a `(scope, id)` pair, so
+   * traversal resolves a target across ALL scopes that hold that id. When two
+   * scopes reuse a stem, following an edge to it reaches every match. This
+   * mirrors the `backlinks` index, which is also keyed by bare id. Scope-
+   * qualified link resolution is intentionally out of scope for Phase C and
+   * would be an additive change here (and to {@link IEdge} / the index).
+   */
+  private _indexById(): ReadonlyMap<MemoryId, IIndexedMemoryRecord[]> {
+    const byId: Map<MemoryId, IIndexedMemoryRecord[]> = new Map<MemoryId, IIndexedMemoryRecord[]>();
+    for (const entry of this._index.entries()) {
+      const id: MemoryId = entry.record.envelope.id;
+      const existing: IIndexedMemoryRecord[] | undefined = byId.get(id);
+      if (existing === undefined) {
+        byId.set(id, [entry]);
+      } else {
+        existing.push(entry);
+      }
+    }
+    return byId;
+  }
+
+  /** Outbound neighbors: the targets of every edge on the records with this id. */
+  private _outbound(id: MemoryId, byId: ReadonlyMap<MemoryId, IIndexedMemoryRecord[]>): MemoryId[] {
+    const targets: MemoryId[] = [];
+    const matches: IIndexedMemoryRecord[] | undefined = byId.get(id);
+    if (matches !== undefined) {
+      for (const entry of matches) {
+        for (const edge of entry.record.envelope.links) {
+          targets.push(edge.target);
+        }
+      }
+    }
+    return targets;
+  }
+
+  /** Inbound neighbors: the ids whose edges point AT this id (the backlinks). */
+  private _inbound(id: MemoryId): ReadonlyArray<MemoryId> {
+    return this._index.backlinks(id);
+  }
+}

package/src/packlets/retrieve/recencyRetriever.ts

@@ -0,0 +1,54 @@
+/*
+ * 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 the query's scope / kind / tag / predicate filters,
+ * ordered most-recently-updated first. The universal v1 retriever — an empty
+ * query returns the whole vault in recency order.
+ * @public
+ */
+export class RecencyRetriever 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<RecencyRetriever> {
+    return succeed(new RecencyRetriever(index));
+  }
+
+  /** {@inheritDoc IMemoryRetriever.retrieve} */
+  public retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>> {
+    return Promise.resolve(
+      guardRetrieverCapabilities(query, this.capabilities).onSuccess(() => {
+        const ordered: IMemoryRecord<unknown>[] = selectByQuery(this._index.entries(), query).sort(
+          recencyCompare
+        );
+        return succeed(limitRecords(ordered, query.limit));
+      })
+    );
+  }
+}