@fgv/ts-agent-memory 5.1.0-36

package/src/packlets/converters/envelopeConverter.ts

@@ -0,0 +1,210 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Converter, Converters, Result, fail, succeed } from '@fgv/ts-utils';
+import { Yaml } from '@fgv/ts-extras';
+import { Convert, IEdge, IMemoryEnvelope, IMemoryRecord, IProvenance, ITemporalBlock } from '../types';
+import { IBodyConverterRegistry } from './bodyConverterRegistry';
+
+/** Matches exactly the JSON `null` literal. */
+// eslint-disable-next-line @rushstack/no-new-null -- the envelope nullable fields (invalid_at, embeddingRef) carry meaningful null; design-lock §2.3-2.5
+const nullConverter: Converter<null> = Converters.generic<null>((from: unknown) =>
+  from === null ? succeed(null) : fail('expected null')
+);
+
+/** A nullable epoch-ms value (`number | null`). */
+// eslint-disable-next-line @rushstack/no-new-null -- meaningful null for IEdge/ITemporalBlock.invalid_at; design-lock §2.3-2.4
+const numberOrNull: Converter<number | null> = Converters.oneOf<number | null>([
+  Converters.number,
+  nullConverter
+]);
+
+/** A nullable string value (`string | null`). */
+// eslint-disable-next-line @rushstack/no-new-null -- meaningful null for IMemoryEnvelope.embeddingRef; design-lock §2.5
+const stringOrNull: Converter<string | null> = Converters.oneOf<string | null>([
+  Converters.string,
+  nullConverter
+]);
+
+/**
+ * Converter for the known {@link IProvenance} fields. The full
+ * {@link provenanceConverter} layers extension-key preservation on top.
+ */
+const knownProvenanceConverter: Converter<IProvenance> = Converters.object<IProvenance>(
+  {
+    source: Converters.string,
+    by: Converters.string.optional(),
+    model: Converters.string.optional(),
+    confidence: Converters.number.optional(),
+    derivedFrom: Convert.memoryId.optional()
+  },
+  { optionalFields: ['by', 'model', 'confidence', 'derivedFrom'] }
+);
+
+/**
+ * Converter for {@link IProvenance}. Validates the known fields and preserves
+ * any extension keys verbatim (the `[key: string]: unknown` opaque payload),
+ * so a round-trip never drops consumer-attached data.
+ * @public
+ */
+export const provenanceConverter: Converter<IProvenance> = Converters.generic<IProvenance>(
+  (from: unknown): Result<IProvenance> =>
+    knownProvenanceConverter.convert(from).onSuccess((known) => {
+      // `from` is guaranteed to be a non-null object here — the known-field
+      // converter only succeeds on objects. Spread the original keys first,
+      // then the validated/normalized known fields on top, so extension keys
+      // survive while the known fields carry their converted values.
+      const merged: IProvenance = { ...(from as Record<string, unknown>), ...known };
+      return succeed(merged);
+    })
+);
+
+/**
+ * Converter for an attributed {@link IEdge}.
+ * @public
+ */
+export const edgeConverter: Converter<IEdge> = Converters.object<IEdge>(
+  {
+    type: Convert.linkType,
+    target: Convert.memoryId,
+    confidence: Converters.number.optional(),
+    provenance: provenanceConverter.optional(),
+    valid_at: Converters.number.optional(),
+    invalid_at: numberOrNull.optional()
+  },
+  { optionalFields: ['confidence', 'provenance', 'valid_at', 'invalid_at'] }
+);
+
+/**
+ * Converter for the optional {@link ITemporalBlock}.
+ * @public
+ */
+export const temporalConverter: Converter<ITemporalBlock> = Converters.object<ITemporalBlock>(
+  {
+    valid_at: Converters.number.optional(),
+    invalid_at: numberOrNull.optional()
+  },
+  { optionalFields: ['valid_at', 'invalid_at'] }
+);
+
+/**
+ * Converter for the invariant {@link IMemoryEnvelope}. Validates a plain
+ * object (e.g. parsed YAML frontmatter) into a typed envelope.
+ * @public
+ */
+export const envelopeConverter: Converter<IMemoryEnvelope> = Converters.object<IMemoryEnvelope>(
+  {
+    id: Convert.memoryId,
+    entityId: Convert.entityId,
+    kind: Convert.kind,
+    tags: Converters.arrayOf(Convert.tag),
+    links: Converters.arrayOf(edgeConverter),
+    created: Converters.number,
+    updated: Converters.number,
+    seq: Converters.number,
+    contentHash: Converters.string,
+    provenance: provenanceConverter,
+    temporal: temporalConverter.optional(),
+    embeddingRef: stringOrNull.optional()
+  },
+  { optionalFields: ['temporal', 'embeddingRef'] }
+);
+
+/**
+ * Converter that parses a YAML frontmatter string into an
+ * {@link IMemoryEnvelope}.
+ * @public
+ */
+export const envelopeYamlConverter: Converter<IMemoryEnvelope> = Yaml.yamlConverter(envelopeConverter);
+
+/** The frontmatter delimiter line. */
+const FRONTMATTER_DELIMITER: string = '---';
+
+/**
+ * The two parts of a memory file: the YAML frontmatter (between the `---`
+ * delimiters) and the markdown body (everything after the closing delimiter).
+ * @public
+ */
+export interface IMemoryFileParts {
+  /** The raw YAML frontmatter (delimiters stripped). */
+  readonly frontmatter: string;
+  /** The raw body text following the closing delimiter. */
+  readonly body: string;
+}
+
+/**
+ * Split a `---\n<yaml>\n---\n<body>` memory file into its frontmatter and
+ * body parts. Pure string handling — no external dependency.
+ * @public
+ */
+export function splitFrontmatter(raw: string): Result<IMemoryFileParts> {
+  // Split on '\n' and strip a trailing '\r' per line so CRLF-authored files
+  // parse identically to LF — otherwise the '\r' would ride along into the
+  // returned frontmatter (perturbing YAML parsing) and body (corrupting
+  // round-trip fidelity).
+  const lines: string[] = raw.split('\n').map((line) => (line.endsWith('\r') ? line.slice(0, -1) : line));
+  if (lines[0].trim() !== FRONTMATTER_DELIMITER) {
+    return fail("memory file: missing opening frontmatter delimiter '---'");
+  }
+  let closeIndex: number = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === FRONTMATTER_DELIMITER) {
+      closeIndex = i;
+      break;
+    }
+  }
+  if (closeIndex === -1) {
+    return fail("memory file: missing closing frontmatter delimiter '---'");
+  }
+  return succeed({
+    frontmatter: lines.slice(1, closeIndex).join('\n'),
+    body: lines.slice(closeIndex + 1).join('\n')
+  });
+}
+
+/**
+ * Join a YAML frontmatter string and a body into the canonical
+ * `---\n<yaml>\n---\n<body>` memory-file format.
+ * @public
+ */
+export function joinFrontmatter(frontmatter: string, body: string): string {
+  const normalized: string = frontmatter.endsWith('\n') ? frontmatter : `${frontmatter}\n`;
+  return `${FRONTMATTER_DELIMITER}\n${normalized}${FRONTMATTER_DELIMITER}\n${body}`;
+}
+
+/**
+ * Parse a complete memory file into a typed {@link IMemoryRecord}. Splits the
+ * frontmatter, validates the envelope, and dispatches the body through the
+ * registered Converter for the envelope's kind.
+ * @public
+ */
+export function parseMemoryFile(
+  raw: string,
+  registry: IBodyConverterRegistry
+): Result<IMemoryRecord<unknown>> {
+  return splitFrontmatter(raw).onSuccess((parts) =>
+    envelopeYamlConverter
+      .convert(parts.frontmatter)
+      .withErrorFormat((msg) => `memory file: invalid envelope: ${msg}`)
+      .onSuccess((envelope) =>
+        registry
+          .convert(envelope.kind, parts.body)
+          .withErrorFormat((msg) => `memory file '${envelope.id}': invalid body: ${msg}`)
+          .onSuccess((body) => succeed({ envelope, body }))
+      )
+  );
+}
+
+/**
+ * Serialize an envelope and its rendered body text into a memory file. The
+ * envelope is emitted as YAML frontmatter; the body is written verbatim after
+ * the closing delimiter.
+ * @public
+ */
+export function serializeMemoryFile(envelope: IMemoryEnvelope, body: string): Result<string> {
+  return Yaml.yamlStringify(envelope)
+    .withErrorFormat((msg) => `memory file '${envelope.id}': failed to serialize envelope: ${msg}`)
+    .onSuccess((frontmatter) => succeed(joinFrontmatter(frontmatter, body)));
+}

package/src/packlets/converters/index.ts

@@ -0,0 +1,7 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './bodyConverterRegistry';
+export * from './envelopeConverter';

package/src/packlets/index/index.ts

@@ -0,0 +1,6 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './memoryIndex';

package/src/packlets/index/memoryIndex.ts

@@ -0,0 +1,268 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Result, succeed } from '@fgv/ts-utils';
+import { IMemoryRecord, Kind, MemoryId, MemoryScopeKey, Tag } from '../types';
+
+/**
+ * The mutation a {@link IMemoryIndex.patch | patch} applies: a record was
+ * written (`'put'`) or removed (`'delete'`).
+ * @public
+ */
+export type MemoryIndexPatchOp = 'put' | 'delete';
+
+/** Shared empty key set for `byKind` / `byTag` misses (avoids per-call allocation). */
+const EMPTY_KEY_SET: ReadonlySet<string> = new Set<string>();
+
+/**
+ * A memory record paired with the {@link MemoryScopeKey | scope} it lives
+ * under. The scope is not carried on the {@link IMemoryEnvelope} (it is derived
+ * from the entity id by the codec), so the store threads it alongside the
+ * record when patching or rebuilding the index. The `(scope, id)` pair is the
+ * index's primary key, keeping records distinct across scopes that reuse a
+ * filename stem (e.g. `turn-0` under different conversations in Phase C).
+ * @public
+ */
+export interface IIndexedMemoryRecord {
+  /** The scope the record is stored under. */
+  readonly scope: MemoryScopeKey;
+  /** The memory record itself. */
+  readonly record: IMemoryRecord<unknown>;
+}
+
+/**
+ * The derived, in-memory secondary indexes the store maintains over its
+ * records. Never the source of truth — the FileTree is. The index is fully
+ * rebuildable from a walk of the store ({@link IMemoryIndex.rebuild}) and is
+ * patched incrementally on every write ({@link IMemoryIndex.patch}).
+ *
+ * @remarks
+ * B1 builds the maps; link-traversal BFS over {@link IMemoryIndex.backlinks}
+ * is B2. The accessors return records (not bare ids) so the B2 retrievers can
+ * consume them directly.
+ * @public
+ */
+export interface IMemoryIndex {
+  /**
+   * Replace the entire index from a full set of records (a store walk).
+   * @returns The number of records indexed.
+   */
+  rebuild(entries: ReadonlyArray<IIndexedMemoryRecord>): Result<number>;
+
+  /**
+   * Apply a single incremental change. `'put'` inserts or replaces the entry
+   * at its `(scope, id)` key (removing any prior associations first); `'delete'`
+   * removes it.
+   * @returns The entry that was applied.
+   */
+  patch(op: MemoryIndexPatchOp, entry: IIndexedMemoryRecord): Result<IIndexedMemoryRecord>;
+
+  /** Every indexed entry (scope + record). Primary read surface for the store. */
+  entries(): ReadonlyArray<IIndexedMemoryRecord>;
+
+  /** Records of the given kind, in recency order (most-recently-updated first). */
+  byKind(kind: Kind): ReadonlyArray<IMemoryRecord<unknown>>;
+
+  /** Records carrying the given tag, in recency order. */
+  byTag(tag: Tag): ReadonlyArray<IMemoryRecord<unknown>>;
+
+  /** All records in recency order (most-recently-updated first). */
+  byRecency(): ReadonlyArray<IMemoryRecord<unknown>>;
+
+  /**
+   * The ids of records whose `links` point AT `target` (inbound edges).
+   * The seed map for B2 link-traversal.
+   */
+  backlinks(target: MemoryId): ReadonlyArray<MemoryId>;
+}
+
+/**
+ * Default in-memory {@link IMemoryIndex}. Maintains the derived `byKind` /
+ * `byTag` / `byRecency` / `backlinks` views incrementally; a `'put'` for an
+ * already-indexed key first removes the prior entry's associations so a changed
+ * kind / tag / link set never leaves a stale reference behind.
+ * @public
+ */
+export class MemoryIndex implements IMemoryIndex {
+  /** Primary store: `(scope, id)` composite key → indexed entry. */
+  private readonly _byKey: Map<string, IIndexedMemoryRecord>;
+  /** kind → set of composite keys. */
+  private readonly _byKind: Map<Kind, Set<string>>;
+  /** tag → set of composite keys. */
+  private readonly _byTag: Map<Tag, Set<string>>;
+  /**
+   * link target id → (source composite key → source id). Keyed by the source's
+   * `(scope, id)` composite — NOT its bare id — so two distinct source records
+   * that share an id across scopes (e.g. `turn-0` in different conversations)
+   * are tracked independently and removing one never drops the other's edge.
+   */
+  private readonly _backlinks: Map<MemoryId, Map<string, MemoryId>>;
+
+  private constructor() {
+    this._byKey = new Map<string, IIndexedMemoryRecord>();
+    this._byKind = new Map<Kind, Set<string>>();
+    this._byTag = new Map<Tag, Set<string>>();
+    this._backlinks = new Map<MemoryId, Map<string, MemoryId>>();
+  }
+
+  /** Family-convention factory. */
+  public static create(): Result<MemoryIndex> {
+    return succeed(new MemoryIndex());
+  }
+
+  /**
+   * The composite primary key for an entry: scope + id, NUL-separated. NUL
+   * is excluded from both components (scope segments pass
+   * `assertPortableFilenameStem`; `MemoryId` is portable-filename-safe), so it
+   * is a collision-proof separator across every scope/id pair the codecs produce.
+   */
+  private static _keyOf(scope: MemoryScopeKey, id: MemoryId): string {
+    return `${scope}\0${id}`;
+  }
+
+  /** {@inheritDoc IMemoryIndex.rebuild} */
+  public rebuild(entries: ReadonlyArray<IIndexedMemoryRecord>): Result<number> {
+    this._byKey.clear();
+    this._byKind.clear();
+    this._byTag.clear();
+    this._backlinks.clear();
+    for (const entry of entries) {
+      this._add(entry);
+    }
+    return succeed(this._byKey.size);
+  }
+
+  /** {@inheritDoc IMemoryIndex.patch} */
+  public patch(op: MemoryIndexPatchOp, entry: IIndexedMemoryRecord): Result<IIndexedMemoryRecord> {
+    const key: string = MemoryIndex._keyOf(entry.scope, entry.record.envelope.id);
+    // Always drop any prior associations for this key first, so a 'put' that
+    // changes kind/tags/links cannot strand a stale reference.
+    this._remove(key);
+    if (op === 'put') {
+      this._add(entry);
+    }
+    return succeed(entry);
+  }
+
+  /** {@inheritDoc IMemoryIndex.entries} */
+  public entries(): ReadonlyArray<IIndexedMemoryRecord> {
+    return Array.from(this._byKey.values());
+  }
+
+  /** {@inheritDoc IMemoryIndex.byKind} */
+  public byKind(kind: Kind): ReadonlyArray<IMemoryRecord<unknown>> {
+    return this._recencyOrdered(this._byKind.get(kind) ?? EMPTY_KEY_SET);
+  }
+
+  /** {@inheritDoc IMemoryIndex.byTag} */
+  public byTag(tag: Tag): ReadonlyArray<IMemoryRecord<unknown>> {
+    return this._recencyOrdered(this._byTag.get(tag) ?? EMPTY_KEY_SET);
+  }
+
+  /** {@inheritDoc IMemoryIndex.byRecency} */
+  public byRecency(): ReadonlyArray<IMemoryRecord<unknown>> {
+    return this._recencyOrdered(this._byKey.keys());
+  }
+
+  /** {@inheritDoc IMemoryIndex.backlinks} */
+  public backlinks(target: MemoryId): ReadonlyArray<MemoryId> {
+    const sources: Map<string, MemoryId> | undefined = this._backlinks.get(target);
+    return sources === undefined ? [] : Array.from(sources.values());
+  }
+
+  /**
+   * Resolve a set of composite keys to their records, ordered
+   * most-recently-updated first (with a `seq` tiebreak so equal-`updated`
+   * records sort deterministically).
+   */
+  private _recencyOrdered(keys: Iterable<string>): ReadonlyArray<IMemoryRecord<unknown>> {
+    const records: IMemoryRecord<unknown>[] = [];
+    for (const key of keys) {
+      const entry: IIndexedMemoryRecord | undefined = this._byKey.get(key);
+      if (entry !== undefined) {
+        records.push(entry.record);
+      }
+    }
+    return records.sort((a, b) => {
+      const byUpdated: number = b.envelope.updated - a.envelope.updated;
+      return byUpdated !== 0 ? byUpdated : b.envelope.seq - a.envelope.seq;
+    });
+  }
+
+  /** Insert an entry and register all its derived associations. */
+  private _add(entry: IIndexedMemoryRecord): void {
+    const key: string = MemoryIndex._keyOf(entry.scope, entry.record.envelope.id);
+    const envelope: IMemoryRecord<unknown>['envelope'] = entry.record.envelope;
+    this._byKey.set(key, entry);
+    this._addToSetMap(this._byKind, envelope.kind, key);
+    for (const tag of envelope.tags) {
+      this._addToSetMap(this._byTag, tag, key);
+    }
+    for (const edge of envelope.links) {
+      this._addBacklink(edge.target, key, envelope.id);
+    }
+  }
+
+  /** Remove the entry at `key` (if present) and all its derived associations. */
+  private _remove(key: string): void {
+    const entry: IIndexedMemoryRecord | undefined = this._byKey.get(key);
+    if (entry === undefined) {
+      return;
+    }
+    const envelope: IMemoryRecord<unknown>['envelope'] = entry.record.envelope;
+    this._byKey.delete(key);
+    this._removeFromSetMap(this._byKind, envelope.kind, key);
+    for (const tag of envelope.tags) {
+      this._removeFromSetMap(this._byTag, tag, key);
+    }
+    for (const edge of envelope.links) {
+      this._removeBacklink(edge.target, key);
+    }
+  }
+
+  /** Register `sourceId` (keyed by its composite `sourceKey`) as linking at `target`. */
+  private _addBacklink(target: MemoryId, sourceKey: string, sourceId: MemoryId): void {
+    const existing: Map<string, MemoryId> | undefined = this._backlinks.get(target);
+    if (existing === undefined) {
+      this._backlinks.set(target, new Map<string, MemoryId>([[sourceKey, sourceId]]));
+    } else {
+      existing.set(sourceKey, sourceId);
+    }
+  }
+
+  /** Drop the backlink from `sourceKey` to `target`, removing the target map when empty. */
+  private _removeBacklink(target: MemoryId, sourceKey: string): void {
+    const existing: Map<string, MemoryId> | undefined = this._backlinks.get(target);
+    if (existing === undefined) {
+      return;
+    }
+    existing.delete(sourceKey);
+    if (existing.size === 0) {
+      this._backlinks.delete(target);
+    }
+  }
+
+  /** Add `member` to the set at `mapKey`, creating the set on first use. */
+  private _addToSetMap<K, M>(map: Map<K, Set<M>>, mapKey: K, member: M): void {
+    const existing: Set<M> | undefined = map.get(mapKey);
+    if (existing === undefined) {
+      map.set(mapKey, new Set<M>([member]));
+    } else {
+      existing.add(member);
+    }
+  }
+
+  /** Remove `member` from the set at `mapKey`, dropping the set when empty. */
+  private _removeFromSetMap<K, M>(map: Map<K, Set<M>>, mapKey: K, member: M): void {
+    const existing: Set<M> | undefined = map.get(mapKey);
+    if (existing === undefined) {
+      return;
+    }
+    existing.delete(member);
+    if (existing.size === 0) {
+      map.delete(mapKey);
+    }
+  }
+}

package/src/packlets/observe/index.ts

@@ -0,0 +1,7 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './observer';
+export * from './memoryObservationStore';

package/src/packlets/observe/memoryObservationStore.ts

@@ -0,0 +1,153 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Collections, Result, fail, succeed } from '@fgv/ts-utils';
+import { IMemoryObservationQuery, IMemoryObservationRecord, IMemoryObserver } from './observer';
+
+/**
+ * Construction options for {@link MemoryObservationStore.create}.
+ * @public
+ */
+export interface IMemoryObservationStoreCreateParams {
+  /**
+   * Maximum number of observation records retained before the oldest is
+   * overwritten. Defaults to `1000`. Must be a positive integer if supplied.
+   */
+  readonly maxRecords?: number;
+}
+
+/**
+ * The default in-memory observation store: an {@link IMemoryObserver} that
+ * retains the records it observes in a bounded ring and answers schema-aware
+ * {@link MemoryObservationStore.query | queries} over them.
+ *
+ * @remarks
+ * **Privacy posture — this store is most-permissive by design.** It retains
+ * every field of every record verbatim, including any `provenance` and
+ * `querySnapshot`. The library bakes in **no** redaction, retention, or
+ * field-stripping policy — that is deployment policy, not library policy. A
+ * deployment that must redact wraps this store with its own
+ * {@link IMemoryObserver} that transforms records before forwarding, or
+ * substitutes a different observer entirely. Size is the only bounded
+ * dimension, via `maxRecords`.
+ *
+ * The store composes `RetainingRingBuffer` from `@fgv/ts-utils` (it does not
+ * hand-roll a ring) and implements {@link IMemoryObserver} directly — `observe`
+ * (the hook) and `query` (the read surface) live on the same class. Wire it via
+ * {@link IFileTreeMemoryStoreCreateParams.observers}. `seq` and `timestamp` are
+ * assigned by the firing authority (the store) before `observe`, so this store
+ * never mints them.
+ * @public
+ */
+export class MemoryObservationStore implements IMemoryObserver {
+  /**
+   * The bounded ring of observed records. The firing authority assigns each
+   * record's `seq`, so the ring's monotonic-`seq` cursor contract is satisfied
+   * by that authority's per-instance counter.
+   * @internal
+   */
+  private readonly _buffer: Collections.RetainingRingBuffer<IMemoryObservationRecord>;
+
+  /**
+   * @param buffer - The pre-constructed backing ring buffer.
+   * @internal
+   */
+  private constructor(buffer: Collections.RetainingRingBuffer<IMemoryObservationRecord>) {
+    this._buffer = buffer;
+  }
+
+  /**
+   * The highest `seq` observed so far. Hold this value and pass it as
+   * `sinceSeq` to {@link MemoryObservationStore.query | query} to page only
+   * records observed afterward. Stable across ring eviction and
+   * {@link MemoryObservationStore.clear | clear}.
+   */
+  public get lastSeq(): number {
+    return this._buffer.lastSeq;
+  }
+
+  /**
+   * The number of records currently retained.
+   */
+  public get size(): number {
+    return this._buffer.size;
+  }
+
+  /**
+   * Family-convention factory.
+   * @param params - {@link IMemoryObservationStoreCreateParams | Construction options}.
+   * @returns On success, a new store. Fails if `maxRecords` is supplied and is
+   * not a positive integer.
+   */
+  public static create(params?: IMemoryObservationStoreCreateParams): Result<MemoryObservationStore> {
+    const maxRecords: number | undefined = params?.maxRecords;
+    if (maxRecords !== undefined && (!Number.isInteger(maxRecords) || maxRecords < 1)) {
+      return fail(`MemoryObservationStore: maxRecords must be a positive integer (got ${maxRecords})`);
+    }
+    return succeed(
+      new MemoryObservationStore(
+        new Collections.RetainingRingBuffer<IMemoryObservationRecord>({ maxRecords })
+      )
+    );
+  }
+
+  /**
+   * {@inheritDoc IMemoryObserver.observe}
+   */
+  public observe(record: IMemoryObservationRecord): Promise<Result<unknown>> {
+    this._buffer.push(record);
+    return Promise.resolve(succeed(record));
+  }
+
+  /**
+   * Returns retained records, oldest-first, narrowed by the supplied criteria.
+   * @param criteria - {@link IMemoryObservationQuery | AND-combined filter criteria}.
+   * @returns The matching records, oldest-first.
+   */
+  public query(criteria?: IMemoryObservationQuery): ReadonlyArray<IMemoryObservationRecord> {
+    return this._buffer.query({
+      sinceSeq: criteria?.sinceSeq,
+      limit: criteria?.limit,
+      filter:
+        criteria === undefined ? undefined : (record) => MemoryObservationStore._matches(record, criteria)
+    });
+  }
+
+  /**
+   * Clears all retained records. Does NOT reset
+   * {@link MemoryObservationStore.lastSeq | lastSeq}, so a held `sinceSeq`
+   * cursor never re-sees a sequence number.
+   */
+  public clear(): void {
+    this._buffer.clear();
+  }
+
+  /**
+   * Tests a record against the non-`seq`/`limit` criteria (those are applied by
+   * the ring buffer itself).
+   * @internal
+   */
+  private static _matches(record: IMemoryObservationRecord, criteria: IMemoryObservationQuery): boolean {
+    if (criteria.since !== undefined && record.timestamp < criteria.since) {
+      return false;
+    }
+    if (criteria.until !== undefined && record.timestamp > criteria.until) {
+      return false;
+    }
+    if (criteria.scope !== undefined && record.scope !== criteria.scope) {
+      return false;
+    }
+    if (criteria.kind !== undefined && record.kind !== criteria.kind) {
+      return false;
+    }
+    if (criteria.phase !== undefined && record.phase !== criteria.phase) {
+      return false;
+    }
+    if (criteria.outcome !== undefined && record.outcome !== criteria.outcome) {
+      return false;
+    }
+    return true;
+  }
+}