@fgv/ts-agent-memory 5.1.0-36

package/dist/ts-agent-memory.d.ts

@@ -0,0 +1,1901 @@
+import { Brand } from '@fgv/ts-utils';
+import { Converter } from '@fgv/ts-utils';
+import { FileTree } from '@fgv/ts-json-base';
+import { JsonSchema } from '@fgv/ts-json-base';
+import { Logging } from '@fgv/ts-utils';
+import { Result } from '@fgv/ts-utils';
+
+/**
+ * The admission decision returned by {@link IWritePolicy.admit}.
+ * @public
+ */
+export declare type AdmissionDecision = {
+    readonly decision: 'accept';
+} | {
+    readonly decision: 'reject';
+    readonly reason: string;
+} | {
+    readonly decision: 'cull-oldest';
+    /** {@link MemoryId}s to evict before writing the incoming record. */
+    readonly evict: ReadonlyArray<MemoryId>;
+};
+
+/**
+ * Validates a single filename stem against the POSIX portable filename set
+ * (`[A-Za-z0-9._-]`), rejecting a leading or trailing `.` and reserved Windows
+ * device names. This is the cross-platform filename-stem contract for the
+ * package: {@link MemoryId} values, the concrete {@link IIdentityCodec}
+ * implementations, and the store's `verifyFilenameId` all gate on it.
+ *
+ * @remarks
+ * A trailing `.` is rejected because Windows silently strips trailing dots from
+ * filenames, so such a stem would not round-trip verbatim through the file
+ * layer even though it is otherwise portable-set-valid.
+ * @public
+ */
+export declare function assertPortableFilenameStem(stem: string): Result<string>;
+
+/**
+ * Default in-memory {@link IBodyConverterRegistry}.
+ *
+ * @remarks
+ * Both `register` and `registerSchema` adapt the supplied converter/validator
+ * into a `Converter<unknown>` via `Converters.generic`, so the heterogeneous
+ * per-kind types are stored uniformly with no cast and no `any`. A
+ * `Converter<T>` is not structurally a `Converter<unknown>` (the `map` callback
+ * makes the type invariant), so the `generic` wrapper — whose callback returns
+ * `Result<T>` (assignable to `Result<unknown>`) — is the type-safe bridge.
+ * @public
+ */
+export declare class BodyConverterRegistry implements IBodyConverterRegistry {
+    private readonly _converters;
+    private constructor();
+    /** Family-convention factory. */
+    static create(): Result<BodyConverterRegistry>;
+    /** {@inheritDoc IBodyConverterRegistry.register} */
+    register<T>(kind: Kind, converter: Converter<T>): void;
+    /** {@inheritDoc IBodyConverterRegistry.registerSchema} */
+    registerSchema<T>(kind: Kind, schema: JsonSchema.ISchemaValidator<T>): void;
+    /** {@inheritDoc IBodyConverterRegistry.has} */
+    has(kind: Kind): boolean;
+    /** {@inheritDoc IBodyConverterRegistry.getConverter} */
+    getConverter(kind: Kind): Result<Converter<unknown>>;
+    /** {@inheritDoc IBodyConverterRegistry.convert} */
+    convert(kind: Kind, body: unknown): Result<unknown>;
+}
+
+/**
+ * Converters for the branded identifier scalars. Each validates an `unknown`
+ * value into the corresponding brand, enforcing the shared hygiene
+ * (non-empty, length-capped, trimmed).
+ * @public
+ */
+export declare const Convert: {
+    readonly memoryId: Converter<MemoryId>;
+    readonly entityId: Converter<EntityId>;
+    readonly kind: Converter<Kind>;
+    readonly tag: Converter<Tag>;
+    readonly scopeKey: Converter<MemoryScopeKey>;
+    readonly linkType: Converter<LinkType>;
+};
+
+/**
+ * The granularity at which the store deduplicates an incoming write against the
+ * existing vault, declared per kind via {@link IWritePolicy.dedupScope}.
+ *
+ * - `'content'`: scope-wide cross-id content dedup. An identical
+ *   `{ kind, body, links }` triple ANYWHERE in the scope — even under a
+ *   different id — is a no-op that returns the existing record. The knowledge
+ *   kind family uses this.
+ * - `'entity'`: same-id content dedup only. An identical re-put of the SAME
+ *   entity is a no-op, but two DISTINCT entities with identical content never
+ *   collapse. The experience (memory) kind families use this so that, e.g.,
+ *   two turns whose summaries happen to be byte-identical both persist.
+ * @public
+ */
+export declare type DedupScope = 'content' | 'entity';
+
+/**
+ * The default {@link DedupScope} applied when a policy does not declare one.
+ * Entity-scoped dedup is the safe default — it never silently collapses two
+ * distinct entities with coincidentally-identical content.
+ * @public
+ */
+export declare const DEFAULT_DEDUP_SCOPE: DedupScope;
+
+/**
+ * Encode a {@link MemoryScopeKey} to its on-disk directory path. The scope may
+ * be multi-segment (`/`-separated) — each component is validated independently
+ * against the POSIX portable filename set (via
+ * {@link assertPortableFilenameStem}), then rejoined with `/`.
+ *
+ * @remarks
+ * This is the day-one multi-segment scope resolver design-lock §9.1 calls for:
+ * the knowledge scope is the single segment `knowledge`, while the Phase-C MTM
+ * scope `conversations/<conversationId>` is two segments. Validating each
+ * segment independently (rather than the whole path as one stem, which the
+ * `ts-prompt-assist` default encoding does) keeps the Phase-C codec additive —
+ * no scope-encoding change is needed when MTM ships.
+ * @public
+ */
+export declare function defaultMemoryScopeEncoding(scope: MemoryScopeKey): Result<string>;
+
+/**
+ * Converter for an attributed {@link IEdge}.
+ * @public
+ */
+export declare const edgeConverter: Converter<IEdge>;
+
+/**
+ * Consumer-supplied domain key. The stable entity identity across versions;
+ * the package never mints identity. Equals {@link MemoryId} for non-temporal
+ * kinds.
+ * @public
+ */
+export declare type EntityId = Brand<string, 'EntityId'>;
+
+/**
+ * Converter for the invariant {@link IMemoryEnvelope}. Validates a plain
+ * object (e.g. parsed YAML frontmatter) into a typed envelope.
+ * @public
+ */
+export declare const envelopeConverter: Converter<IMemoryEnvelope>;
+
+/**
+ * Converter that parses a YAML frontmatter string into an
+ * {@link IMemoryEnvelope}.
+ * @public
+ */
+export declare const envelopeYamlConverter: Converter<IMemoryEnvelope>;
+
+/**
+ * Flat-layout, FileTree-backed {@link IMemoryStore}. The FileTree is the source
+ * of truth; the {@link IMemoryIndex} is a derived in-memory view patched on
+ * every write. Concurrent writes are serialized through a per-instance async
+ * write-lock so the index and the on-disk files never interleave.
+ *
+ * @remarks
+ * B1 supports flat (non-versioned) layout only and string (markdown) bodies.
+ * A codec reporting `isVersioned: true`, or a non-string body, fails loudly —
+ * the versioned/temporal write path is a fast-follow.
+ * @public
+ */
+export declare class FileTreeMemoryStore implements IMemoryStore {
+    private readonly _root;
+    private readonly _registry;
+    private readonly _writePolicies;
+    private readonly _codecs;
+    private readonly _defaultCodec;
+    private readonly _defaultPolicy;
+    private readonly _scopeEncoding;
+    private readonly _clock;
+    private readonly _index;
+    private readonly _hasher;
+    private readonly _observers;
+    private readonly _logger;
+    private readonly _vectorIndex;
+    private readonly _embed;
+    /** Monotonic write counter; incremented inside the write-lock on each put. */
+    private _seq;
+    /**
+     * Monotonic observation-sequence counter. A distinct authority from `_seq`
+     * (the envelope write counter): it numbers the audit stream so a single
+     * {@link MemoryObservationStore} fed by this store sees strictly increasing
+     * `seq`, satisfying the ring buffer's cursor contract.
+     */
+    private _observationSeq;
+    /** Tail of the write-lock promise chain that serializes mutating ops. */
+    private _writeTail;
+    /**
+     * The record-level mutable-field vocabulary: maps a declared mutable field
+     * name to its canonical location on a record. Used to project an incoming
+     * record into a merge-patch on update. B1 ships the knowledge-LWW surface
+     * (body + envelope metadata); body-internal mutable fields (Phase-C cap-cull)
+     * extend this map.
+     */
+    private static readonly _mutableFieldAccessors;
+    private constructor();
+    /**
+     * Family-convention factory. Builds the derived index and a default LWW
+     * policy, then performs an initial FileTree walk so an existing vault is
+     * indexed (and the `seq` counter resumes past the highest persisted `seq`).
+     */
+    static create(params: IFileTreeMemoryStoreCreateParams): Result<FileTreeMemoryStore>;
+    /** {@inheritDoc IMemoryStore.get} */
+    get(kind: Kind, entityId: EntityId): Promise<Result<IMemoryRecord<unknown> | undefined>>;
+    /** {@inheritDoc IMemoryStore.getById} */
+    getById(scope: MemoryScopeKey, id: MemoryId): Promise<Result<IMemoryRecord<unknown> | undefined>>;
+    /** {@inheritDoc IMemoryStore.list} */
+    list(filter?: IMemoryStoreListFilter): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+    /** {@inheritDoc IMemoryStore.put} */
+    put(record: IMemoryRecord<unknown>): Promise<Result<IMemoryRecord<unknown>>>;
+    /** {@inheritDoc IMemoryStore.delete} */
+    delete(kind: Kind, entityId: EntityId): Promise<Result<MemoryId>>;
+    /**
+     * Serialize a mutating task behind the write-lock. Tasks run in submission
+     * order; a failed task does not break the chain for subsequent ones.
+     */
+    private _enqueue;
+    /**
+     * Build and fan out one observation record for a completed op. A no-op when no
+     * observers are wired (the additive-default path pays nothing). The store is
+     * the seq authority — it mints `seq` / `timestamp` so every observer sees the
+     * same record. The scope is resolved best-effort via the codec.
+     */
+    private _fireObservation;
+    /** Invoke one observer, swallowing any failure or throw (logged at `warn`). */
+    private _safeObserve;
+    /**
+     * Log a swallowed-issue warning (observer failure or best-effort vector
+     * maintenance), tolerating a logger that itself throws — diagnostic logging
+     * must never make a store op reject.
+     */
+    private _warnSwallowed;
+    /** Resolve a scope for an observation, best-effort (undefined when unresolvable). */
+    private _scopeBestEffort;
+    private _putLocked;
+    /**
+     * Run dedup → policy → stamp → embed → write for a resolved address and content
+     * hash. Async because the embed-on-write hook (when wired) does a network call
+     * or in-process inference; the whole chain runs inside the write-lock so the
+     * vector index, the on-disk file, and the derived index never interleave.
+     */
+    private _writeResolved;
+    /**
+     * Build → embed → persist → evict for an admitted write.
+     *
+     * The durable record store is authoritative; the vector index is a **derived,
+     * rebuildable** view, so vector maintenance is **best-effort** — a failed embed
+     * or `add` is logged and the durable write still succeeds (the index can be
+     * rebuilt via {@link InMemoryCosineIndex.rebuild}). Only genuine record-store
+     * failures (body/codec/policy, persist, file eviction) fail the `put`.
+     *
+     * Ordering: the embed + `add` run immediately before the single `_persist` so
+     * the index-returned `embeddingRef` lands in one durable write (a post-persist
+     * stamp would need a second write whose failure path is effectively untestable).
+     * Build and persist the replacement BEFORE evicting the cull-oldest cohort, so a
+     * later eviction failure never loses data with nothing written in its place.
+     */
+    private _admitWrite;
+    /**
+     * Best-effort embed-on-write. When a vector index AND an embedder are wired,
+     * embeds the built record, `add`s the vector (replace semantics handle a same-id
+     * re-embed — no explicit remove), and stamps the returned `embeddingRef`. A
+     * failure (returned `fail` OR a thrown/rejected hook) is logged and the
+     * unembedded record is returned unchanged — the put still persists, and the
+     * derived index is reconciled by a later `rebuild`. A pass-through no-op when
+     * unwired (byte-identical record).
+     *
+     * Always succeeds (`Result` is the chain's shape, never a vector-induced
+     * failure).
+     */
+    private _embedOnWrite;
+    /**
+     * Evict the records named by a `cull-oldest` decision, best-effort. Runs only
+     * after the authoritative `_persist`, so a failed eviction is logged (never
+     * fatal) and the cap self-corrects on the next admission. Returns the ids that
+     * were actually evicted (so observations / vector pruning cover only those).
+     * `accept` / `reject` decisions evict nothing.
+     */
+    private _applyEvictions;
+    /** Best-effort vector removal for each evicted record (never fails the put). */
+    private _removeEvictedVectors;
+    /**
+     * Run a consumer-supplied vector hook, normalizing a thrown/rejected hook into a
+     * `Failure` and logging any failure at `warn`. Best-effort: the caller proceeds
+     * regardless, since the index is rebuildable.
+     */
+    private _tryVectorOp;
+    /**
+     * Best-effort vector removal. A no-op unless the full vector lifecycle is wired
+     * (both an index AND an embedder), so an unwired store does no vector work and
+     * behaves byte-identically. Failures are logged, never surfaced — a committed
+     * delete/eviction must not fail because a derived index could not be pruned.
+     */
+    private _removeVectorBestEffort;
+    /**
+     * Build the record to persist. On a first write the incoming envelope is the
+     * base (final content equals the incoming content, so the dedup `hash` is
+     * reused). On an update the incoming record's mutable fields are projected into
+     * a merge-patch and the policy's `applyUpdate` merges them over the existing
+     * record (preserving `created`); the persisted body and `contentHash` are then
+     * taken from the policy's actual output, so a body-transforming policy is never
+     * bypassed and the stored hash always matches the stored `{ kind, body, links }`.
+     * The store stamps the transaction-time metadata it owns
+     * (`created` / `updated` / `seq` / `contentHash`).
+     */
+    private _buildRecord;
+    /** Serialize and write a fully-stamped record, then patch the index. */
+    private _persist;
+    private _deleteLocked;
+    /** Evict (physically delete) a single record file by id, patching the index. */
+    private _evict;
+    /** Project the incoming record's mutable fields into a merge-patch. */
+    private _projectMutablePatch;
+    /**
+     * The admission cohort for a write: every indexed record in `scope` of `kind`
+     * except the one at `idStem` (the record being written or updated). This is
+     * the set a per-kind cap (e.g. {@link MemoryCapCullPolicy}) counts against, so
+     * a bounded-ring policy can keep a per-scope/per-kind family within
+     * `maxRecords`. Excluding the target id makes the post-write count uniform
+     * across first-writes and updates.
+     */
+    private _admissionCohort;
+    /** Find a record in `scope` whose `contentHash` equals `hash`, if any. */
+    private _findByContentHash;
+    private _contentHash;
+    private _codecFor;
+    private _policyFor;
+    /**
+     * Read and validate the record at `<scope>/<idStem>.md`, returning `undefined`
+     * when the scope directory or file is absent. Verifies the on-disk id ↔
+     * filename round-trip on every load.
+     */
+    private _readRecord;
+    /** Enforce `envelope.id === filename stem` and the codec round-trip on load. */
+    private _verifyLoaded;
+    /**
+     * Resolve the directory for a scope, returning `undefined` when it does not
+     * exist. Navigation only — does not create. Folds the path segments through
+     * `getChildren` so an absent segment short-circuits to `undefined`.
+     */
+    private _resolveScopeDir;
+    /** Ensure the scope directory exists, creating segments as needed. */
+    private _ensureScopeDir;
+    /** Write (create or overwrite) `<scope>/<idStem>.md` with `raw`. */
+    private _writeFile;
+    /**
+     * Physically delete `<scope>/<idStem>.md`. The scope-missing and file-missing
+     * guards are unreachable through the callers (`delete` / `_evict` both read the
+     * record first, so the directory and file exist) but are kept so a future
+     * direct caller degrades loudly rather than silently.
+     */
+    private _deleteFile;
+    /**
+     * Walk the FileTree once and rebuild the index. Also resumes the `seq`
+     * counter past the highest persisted `seq` so new writes stay monotonic.
+     */
+    private _initialIndex;
+    /** Recursively collect every `.md` record under `dir` (scope = path segments). */
+    private _collectEntries;
+}
+
+/**
+ * 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 declare function guardRetrieverCapabilities(query: IMemoryQuery, capabilities: IMemoryRetrieverCapabilities): Result<true>;
+
+/**
+ * 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 declare class HybridRetriever implements IMemoryRetriever {
+    private readonly _retrievers;
+    private readonly _mergeStrategy;
+    private readonly _capabilities;
+    private constructor();
+    /** {@inheritDoc IMemoryRetriever.capabilities} */
+    get capabilities(): IMemoryRetrieverCapabilities;
+    /**
+     * Family-convention factory.
+     * @param retrievers - The retrievers to compose (at least one).
+     * @param mergeStrategy - How to combine their results.
+     */
+    static create(retrievers: ReadonlyArray<IMemoryRetriever>, mergeStrategy: IMergeStrategy): Result<HybridRetriever>;
+    /** {@inheritDoc IMemoryRetriever.retrieve} */
+    retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+    /**
+     * 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;
+}
+
+/**
+ * Registry of per-kind body Converters. Each memory {@link Kind} registers the
+ * validated shape of its body; the store dispatches an `unknown` body through
+ * the registered Converter on every write. Type-safe — no `any`.
+ * @public
+ */
+export declare interface IBodyConverterRegistry {
+    /**
+     * Register a Converter for a kind. Replaces any prior registration for the
+     * same kind.
+     */
+    register<T>(kind: Kind, converter: Converter<T>): void;
+    /**
+     * Register a `JsonSchema` validator (from `@fgv/ts-json-base`) for a kind —
+     * the schema IS a Validator. Replaces any prior registration for the same
+     * kind.
+     */
+    registerSchema<T>(kind: Kind, schema: JsonSchema.ISchemaValidator<T>): void;
+    /** Returns `true` if a converter is registered for the kind. */
+    has(kind: Kind): boolean;
+    /**
+     * Get the raw converter registered for a kind. Fails if the kind is
+     * unregistered. Exposed for implementors that need to re-validate a patched
+     * body (e.g. a temporal-versioned policy's `applyUpdate`).
+     */
+    getConverter(kind: Kind): Result<Converter<unknown>>;
+    /**
+     * Convert an `unknown` body value for the given kind. Fails with
+     * `no converter registered for kind '<k>'` when unregistered.
+     */
+    convert(kind: Kind, body: unknown): Result<unknown>;
+}
+
+/**
+ * An attributed link between two records. Carries the relation type, the
+ * target id, and optional confidence / provenance / world-truth validity.
+ * Replaces bare string references (e.g. PersonAIlity's `IMtmRef` becomes an
+ * `IEdge` with `type: LinkType('mtm-ref')`).
+ * @public
+ */
+export declare interface IEdge {
+    /** Open-vocabulary relation type. */
+    readonly type: LinkType;
+    /** The linked-to record. */
+    readonly target: MemoryId;
+    /** Optional confidence in `[0, 1]`. */
+    readonly confidence?: number;
+    /** Optional structured provenance for the link itself. */
+    readonly provenance?: IProvenance;
+    /** World-truth validity start (epoch ms). Present only on temporal edges. */
+    readonly valid_at?: number;
+    /**
+     * World-truth validity end (epoch ms). `null` = still valid; absent = no
+     * temporal extent.
+     */
+    readonly invalid_at?: number | null;
+}
+
+/**
+ * Parameters for {@link FileTreeMemoryStore.create}.
+ * @public
+ */
+export declare interface IFileTreeMemoryStoreCreateParams {
+    /** Root directory under which scope-encoded sub-trees live. Must be mutable. */
+    readonly root: FileTree.IMutableFileTreeDirectoryItem;
+    /** Per-kind body converter registry. Gates every body on write and read. */
+    readonly registry: IBodyConverterRegistry;
+    /** Per-kind write policies. Kinds without an entry use a default LWW policy. */
+    readonly writePolicies?: ReadonlyMap<Kind, IWritePolicy>;
+    /** Per-kind identity codecs. */
+    readonly codecs?: ReadonlyMap<Kind, IIdentityCodec>;
+    /** Default codec for kinds without an explicit entry. */
+    readonly defaultCodec?: IIdentityCodec;
+    /** Scope encoding. Defaults to {@link defaultMemoryScopeEncoding}. */
+    readonly scopeEncoding?: (scope: MemoryScopeKey) => Result<string>;
+    /**
+     * Transaction-time clock. Defaults to `Date.now`. Injectable so tests can
+     * make `created` / `updated` deterministic. Also stamps observation
+     * `timestamp`s.
+     */
+    readonly clock?: () => number;
+    /**
+     * Optional observers fired once per public `get` / `put` / `delete` call.
+     * Purely additive — when absent, no observation records are produced and the
+     * store behaves exactly as it did without this parameter. Observer errors
+     * never affect the store operation (swallowed, logged to {@link
+     * IFileTreeMemoryStoreCreateParams.logger | logger} at `warn`).
+     */
+    readonly observers?: ReadonlyArray<IMemoryObserver>;
+    /**
+     * Diagnostic logger for swallowed observer failures. Defaults to a
+     * `Logging.NoOpLogger`.
+     */
+    readonly logger?: Logging.ILogger;
+    /**
+     * Optional vector index for semantic recall. Wired together with
+     * {@link IFileTreeMemoryStoreCreateParams.embed | embed}: when both are present
+     * the store embeds each written record and maintains the index on
+     * `put` / `delete` / cap-cull eviction. Absent (or `embed` absent) → no
+     * embedding work happens and the store behaves exactly as it does without this
+     * parameter (the additive, zero-overhead-when-unwired default — mirrors the
+     * observer hook).
+     */
+    readonly vectorIndex?: IVectorIndex;
+    /**
+     * Optional embedder applied to each record on write, wired together with
+     * {@link IFileTreeMemoryStoreCreateParams.vectorIndex | vectorIndex}. The
+     * consumer supplies it (e.g. `callProviderEmbedding` or in-process
+     * transformers); the store never calls an embedding provider directly, so the
+     * core stays embedder-agnostic. Embedding/index maintenance is **best-effort**:
+     * a failed (or throwing) `embed` / `add` / `remove` is logged at `warn` via
+     * {@link IFileTreeMemoryStoreCreateParams.logger | logger} and the record
+     * operation still succeeds — the vector index is a derived view that a later
+     * `rebuild` reconciles, so a vector failure never fails an authoritative write.
+     */
+    readonly embed?: MemoryEmbedder;
+}
+
+/**
+ * Maps a consumer-supplied domain key ⇄ a FileTree storage address. Injected
+ * per kind so the store never touches raw domain keys: the codec owns all
+ * filename escaping and the flat-vs-versioned layout dispatch.
+ * @public
+ */
+export declare interface IIdentityCodec {
+    /**
+     * Encode a consumer-supplied entity id to a FileTree address. Deterministic
+     * and pure — no I/O.
+     */
+    encode(entityId: EntityId): Result<IIdentityCodecResult>;
+    /**
+     * Decode a FileTree address back to the original {@link EntityId}. The exact
+     * inverse of {@link IIdentityCodec.encode | encode} for non-versioned kinds.
+     */
+    decode(scope: MemoryScopeKey, encodedStem: string): Result<EntityId>;
+    /**
+     * Assert that `encode(decode(scope, stem)).idStem === stem`. Used by the
+     * store's `verifyFilenameId` check on load.
+     */
+    verifyRoundTrip(scope: MemoryScopeKey, stem: string): Result<true>;
+}
+
+/**
+ * The FileTree storage address an {@link IIdentityCodec} maps a domain key to.
+ * @public
+ */
+export declare interface IIdentityCodecResult {
+    /** Scope path segment (may be multi-level, e.g. `conversations/<id>`). */
+    readonly scope: MemoryScopeKey;
+    /** Filename stem (the part before `.md`). Filename-safe after encoding. */
+    readonly idStem: string;
+    /**
+     * Whether this kind uses a versioned layout (temporal: multiple files per
+     * entity) vs. a flat layout (one file per entity). Non-temporal = always
+     * `false`.
+     */
+    readonly isVersioned: boolean;
+}
+
+/**
+ * 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 declare interface IIndexedMemoryRecord {
+    /** The scope the record is stored under. */
+    readonly scope: MemoryScopeKey;
+    /** The memory record itself. */
+    readonly record: IMemoryRecord<unknown>;
+}
+
+/**
+ * Parameters for {@link MemoryCapCullPolicy.create}.
+ * @public
+ */
+export declare interface IMemoryCapCullPolicyParams {
+    /**
+     * Maximum number of records the policy admits before culling the oldest.
+     * Counted over the `existing` cohort passed to {@link IWritePolicy.admit}.
+     * Absent = no cap (admission always accepts).
+     */
+    readonly maxRecords?: number;
+    /**
+     * The fields a merge-patch update may touch (drawn from the record-level
+     * mutable vocabulary: `body` / `tags` / `links` / `provenance` /
+     * `embeddingRef`). Fields outside this list are immutable.
+     */
+    readonly mutableFields: ReadonlyArray<string>;
+}
+
+/**
+ * The invariant identity + transaction-time envelope carried by every memory
+ * record, independent of the per-kind body.
+ * @public
+ */
+export declare interface IMemoryEnvelope {
+    /** Stable file-stem identifier. MUST equal the on-disk filename stem. */
+    readonly id: MemoryId;
+    /** Consumer-supplied domain key. Equals {@link IMemoryEnvelope.id | id} for non-temporal kinds. */
+    readonly entityId: EntityId;
+    /** Consumer-registered kind; dispatches the body Converter. */
+    readonly kind: Kind;
+    /** Open-vocabulary tags. */
+    readonly tags: ReadonlyArray<Tag>;
+    /** Attributed outbound edges. */
+    readonly links: ReadonlyArray<IEdge>;
+    /** Epoch ms of the first write. Immutable after creation. */
+    readonly created: number;
+    /** Epoch ms of the most recent write. */
+    readonly updated: number;
+    /**
+     * Monotonic write counter within the store instance, assigned by the store
+     * on every successful put. Enables stable cursor paging over observation
+     * records without a full walk.
+     */
+    readonly seq: number;
+    /**
+     * Content hash over the canonical `{ kind, body, links }`. The dedup key:
+     * an exact match is a no-op upsert that returns the existing record.
+     */
+    readonly contentHash: string;
+    /** Structured provenance (never a flat enum). */
+    readonly provenance: IProvenance;
+    /** Bi-temporal validity. Present only on temporal kinds. */
+    readonly temporal?: ITemporalBlock;
+    /**
+     * Vector-index entry reference, set by the vector index on write. `null` =
+     * not embedded; absent = same as `null` (backwards-compat seam).
+     */
+    readonly embeddingRef?: string | null;
+}
+
+/**
+ * The two parts of a memory file: the YAML frontmatter (between the `---`
+ * delimiters) and the markdown body (everything after the closing delimiter).
+ * @public
+ */
+export declare interface IMemoryFileParts {
+    /** The raw YAML frontmatter (delimiters stripped). */
+    readonly frontmatter: string;
+    /** The raw body text following the closing delimiter. */
+    readonly body: string;
+}
+
+/**
+ * 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 declare 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>;
+}
+
+/**
+ * Query criteria for {@link MemoryObservationStore.query}. All supplied criteria
+ * are AND-combined.
+ * @public
+ */
+export declare 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;
+}
+
+/**
+ * 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 declare 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>>;
+}
+
+/**
+ * Construction options for {@link MemoryObservationStore.create}.
+ * @public
+ */
+export declare 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;
+}
+
+/**
+ * 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 declare 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>>;
+}
+
+/**
+ * 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 declare 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;
+}
+
+/**
+ * A complete memory record: the invariant {@link IMemoryEnvelope} plus the
+ * typed, per-kind body. The store's public surface uses
+ * `IMemoryRecord<unknown>`; consumers narrow `TBody` by checking
+ * `envelope.kind` and validating through the registered Converter.
+ * @public
+ */
+export declare interface IMemoryRecord<TBody = unknown> {
+    /** The invariant identity + transaction-time envelope. */
+    readonly envelope: IMemoryEnvelope;
+    /** The per-kind, Converter-validated body. */
+    readonly body: TBody;
+}
+
+/**
+ * The minimal record-source surface {@link InMemoryCosineIndex.rebuild} reads to
+ * re-embed an entire vault. {@link IMemoryStore} satisfies it structurally (its
+ * `list` accepts an optional filter, which is assignable to this no-argument
+ * shape), so a consumer passes the store directly — without the vector packlet
+ * taking a dependency on the store packlet (which depends on the vector packlet
+ * for {@link IVectorIndex}, so the reverse import would be a cycle).
+ * @public
+ */
+export declare interface IMemoryRecordSource {
+    /** List every record in the vault. */
+    list(): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+}
+
+/**
+ * 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 declare 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 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 declare 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;
+}
+
+/**
+ * The writable, FileTree-backed, content-hash-deduped memory store.
+ * @public
+ */
+export declare interface IMemoryStore {
+    /**
+     * Keyed read by entity id. Resolves `entityId` to a storage address via the
+     * registered {@link IIdentityCodec} for `kind`. Returns `undefined` when no
+     * record exists.
+     */
+    get(kind: Kind, entityId: EntityId): Promise<Result<IMemoryRecord<unknown> | undefined>>;
+    /**
+     * Direct read by `(scope, MemoryId)`. Returns `undefined` when not found.
+     */
+    getById(scope: MemoryScopeKey, id: MemoryId): Promise<Result<IMemoryRecord<unknown> | undefined>>;
+    /**
+     * List records, filtered in-memory over the derived index.
+     */
+    list(filter?: IMemoryStoreListFilter): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+    /**
+     * Write a record. Validates the body, computes a content hash, deduplicates
+     * (scope-wide, before policy), applies the kind's {@link IWritePolicy}, stamps
+     * transaction-time metadata (`created` / `updated` / `seq` / `contentHash`),
+     * writes the file, and patches the index. Returns the written record — or the
+     * existing record unchanged on a dedup no-op.
+     */
+    put(record: IMemoryRecord<unknown>): Promise<Result<IMemoryRecord<unknown>>>;
+    /**
+     * Delete a record by `(kind, entityId)`. Non-temporal kinds physically delete
+     * the file. Returns the {@link MemoryId} of the deleted record.
+     */
+    delete(kind: Kind, entityId: EntityId): Promise<Result<MemoryId>>;
+}
+
+/**
+ * Filter for {@link IMemoryStore.list}. All present fields are ANDed together.
+ * @public
+ */
+export declare interface IMemoryStoreListFilter {
+    /** Restrict to records in this scope. */
+    readonly scope?: MemoryScopeKey;
+    /** Restrict to records of this kind. */
+    readonly kind?: Kind;
+    /** Restrict to records carrying this tag (exact match). */
+    readonly tag?: Tag;
+    /**
+     * For temporal kinds: return only records valid at this epoch ms. No-op in
+     * B1 (no temporal kinds wired).
+     */
+    readonly asOf?: number;
+}
+
+/**
+ * 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 declare 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>>>;
+}
+
+/**
+ * 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 declare function indexedRecordMatchesQuery(entry: IIndexedMemoryRecord, query: IMemoryQuery): boolean;
+
+/**
+ * The brute-force, in-memory cosine {@link IVectorIndex}. Stores one
+ * `Float32Array` per record and answers a query by computing cosine similarity
+ * against every stored vector, returning the top-k by descending score.
+ *
+ * @remarks
+ * This is the **complete** vector implementation for the fgv regime — large-N is
+ * explicitly out of scope (the seam stays open for a consumer to swap an external
+ * ANN backend once N grows beyond "thousands of records"). No external dependency
+ * and no ANN structure: a linear scan over a few thousand vectors is well within
+ * an interactive budget.
+ *
+ * The index has a single dimension established by the first vector added; every
+ * subsequent `add` and every `query` vector must match that dimension or fail
+ * loudly — a mismatched dimension is an embedder-wiring bug, never a silent
+ * zero-similarity result. {@link InMemoryCosineIndex.rebuild | rebuild} clears
+ * the index, so a re-embed with a different model (hence dimension) is supported.
+ *
+ * Persistence (a JSON sidecar) is deliberately out of scope for this layer — the
+ * index is in-memory and rebuilt from the store via `rebuild`; a sidecar is a
+ * future nicety.
+ * @public
+ */
+export declare class InMemoryCosineIndex implements IVectorIndex {
+    private readonly _vectors;
+    /** The dimension of every stored vector; `undefined` until the first `add`. */
+    private _dimension;
+    private constructor();
+    /** The number of vectors currently held. */
+    get size(): number;
+    /** Family-convention factory. */
+    static create(): Result<InMemoryCosineIndex>;
+    /** {@inheritDoc IVectorIndex.add} */
+    add(id: MemoryId, vector: Float32Array): Promise<Result<string>>;
+    /** {@inheritDoc IVectorIndex.remove} */
+    remove(id: MemoryId): Promise<Result<MemoryId>>;
+    /** {@inheritDoc IVectorIndex.query} */
+    query(vector: Float32Array, topK: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
+    /**
+     * Re-embed every record from `source` and rebuild the index from scratch.
+     * Clears the current contents (and the established dimension) first, so a
+     * re-embed with a different model is supported. Returns the number of vectors
+     * indexed.
+     *
+     * On any failure (list, embed, or add) the index is rolled back to empty
+     * rather than left in a partially-rebuilt state — a caller that retries a query
+     * after a failed rebuild sees a clean empty index, never a half-populated one.
+     *
+     * @param source - The record source to re-embed (an {@link IMemoryStore}
+     * satisfies this structurally).
+     * @param embed - The embedder applied to each record.
+     */
+    rebuild(source: IMemoryRecordSource, embed: MemoryEmbedder): Promise<Result<number>>;
+    /** Empty the index and forget the established dimension. */
+    private _reset;
+    /** The Euclidean magnitude (L2 norm) of a vector. */
+    private static _magnitude;
+    /**
+     * Cosine similarity between the query (whose magnitude is precomputed once and
+     * reused across the scan) and a stored vector. A zero-magnitude vector on
+     * either side yields `0` rather than `NaN` — a degenerate vector is simply
+     * maximally dissimilar, not an error.
+     */
+    private static _cosine;
+}
+
+/**
+ * Structured provenance for a record or an edge. Never a flat enum — the
+ * `[key: string]: unknown` index signature lets a consumer attach an opaque
+ * domain payload (e.g. PersonAIlity's sentiment / epistemic blocks) without
+ * changing this interface, while still satisfying the no-`any` rule.
+ * @public
+ */
+export declare interface IProvenance {
+    /** Where the attribution came from. */
+    readonly source: ProvenanceSource;
+    /** Optional human or agent identifier responsible for the write. */
+    readonly by?: string;
+    /** Optional model identifier, when a model produced the content. */
+    readonly model?: string;
+    /** Optional confidence in `[0, 1]`. */
+    readonly confidence?: number;
+    /** Back-link to the source experience record. Enables the cross-kind provenance spine. */
+    readonly derivedFrom?: MemoryId;
+    /** Opaque extension payload — consumer-owned, never interpreted by the store. */
+    readonly [key: string]: unknown;
+}
+
+/**
+ * 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 declare 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 declare 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;
+}
+
+/**
+ * Optional bi-temporal validity block on an envelope. Present only on
+ * temporal kinds; absent = zero cost for atemporal kinds.
+ * @public
+ */
+export declare interface ITemporalBlock {
+    /** World-truth validity start (epoch ms). */
+    readonly valid_at?: number;
+    /** World-truth validity end (epoch ms). `null` = still valid. */
+    readonly invalid_at?: number | null;
+}
+
+/**
+ * The vector-index seam an embedding backend implements to make
+ * {@link SemanticRetriever | semantic recall} operational.
+ *
+ * @remarks
+ * Vectors cross this seam as `Float32Array` (the in-memory representation an
+ * embedding model produces); `number[]` is reserved for the JSON-wire edges
+ * (e.g. a provider's embedding response). The in-package brute-force cosine
+ * implementation is {@link InMemoryCosineIndex}; a consumer can swap an external
+ * ANN backend behind the same seam once N grows beyond the in-memory regime.
+ *
+ * Every operation returns a `Result` (async, since a real backend does I/O) so
+ * failure is explicit and never throws across the seam.
+ * @public
+ */
+export declare interface IVectorIndex {
+    /**
+     * Add (or replace) the embedding for `id`. Returns the opaque
+     * {@link IMemoryEnvelope.embeddingRef | embeddingRef} the store stamps onto
+     * the envelope so a later read knows the record is embedded.
+     */
+    add(id: MemoryId, vector: Float32Array): Promise<Result<string>>;
+    /**
+     * Remove the embedding for `id`. Returns the removed id. Idempotent — removing
+     * an id with no embedding still succeeds (returns the id).
+     */
+    remove(id: MemoryId): Promise<Result<MemoryId>>;
+    /**
+     * Return the `topK` nearest records to `vector`, in descending score order.
+     */
+    query(vector: Float32Array, topK: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
+}
+
+/**
+ * A single hit returned by {@link IVectorIndex.query}: the matched record id and
+ * the backend's similarity score (higher = more similar; the exact scale is
+ * backend-defined). Hits are returned in descending score order.
+ * @public
+ */
+export declare interface IVectorQueryHit {
+    /** The id of the matched record. */
+    readonly id: MemoryId;
+    /** Backend similarity score; higher is more similar. */
+    readonly score: number;
+}
+
+/**
+ * A per-kind write policy, injected at store construction. Invoked AFTER
+ * content-hash dedup (dedup is always pre-policy). The policy decides
+ * admission and, on update, applies a JSON Merge Patch (RFC-7386) restricted
+ * to the declared mutable fields.
+ * @public
+ */
+export declare interface IWritePolicy {
+    /**
+     * Names of the fields a merge-patch update may touch. Fields outside this
+     * list are immutable; a change to one constitutes a new entity (its
+     * `contentHash` differs). Used by {@link IWritePolicy.applyUpdate} to
+     * restrict which fields the patch applies.
+     */
+    readonly mutableFields: ReadonlyArray<string>;
+    /**
+     * The granularity at which the store deduplicates an incoming write for this
+     * kind. Optional; when absent the store applies {@link DEFAULT_DEDUP_SCOPE}
+     * (`'entity'`). See {@link DedupScope}.
+     */
+    readonly dedupScope?: DedupScope;
+    /**
+     * Determine whether the incoming record is admitted.
+     * @param incoming - The record about to be written.
+     * @param existing - The admission cohort the kind's cap applies to: the
+     * records in the same scope of the same kind, EXCLUDING the record at
+     * `incoming`'s target id. Empty on a first write into an empty cohort.
+     * Excluding the target id makes the post-write count uniform
+     * (`existing.length + 1`) across first-writes and same-id updates. A
+     * last-write-wins policy that has no cap ignores this argument.
+     * @returns A {@link AdmissionDecision}.
+     */
+    admit(incoming: IMemoryRecord<unknown>, existing: ReadonlyArray<IMemoryRecord<unknown>>): Result<AdmissionDecision>;
+    /**
+     * Apply a JSON Merge Patch (RFC-7386) to the mutable fields of an existing
+     * record. Called when admission is `accept` AND a record with the same
+     * `entityId` already exists (an update, not a first write).
+     *
+     * @param existing - The current persisted record.
+     * @param patch - A partial JSON object in Merge Patch format. `null`
+     * deletes the corresponding key; arrays replace wholesale; nested objects
+     * deep-merge. Only keys in {@link IWritePolicy.mutableFields} are applied.
+     * @returns The updated record (envelope + body).
+     */
+    applyUpdate(existing: IMemoryRecord<unknown>, patch: Record<string, unknown>): Result<IMemoryRecord<unknown>>;
+}
+
+/**
+ * Join a YAML frontmatter string and a body into the canonical
+ * `---\n<yaml>\n---\n<body>` memory-file format.
+ * @public
+ */
+export declare function joinFrontmatter(frontmatter: string, body: string): string;
+
+/**
+ * Open-vocabulary record classifier. Consumers register one body
+ * {@link https://www.npmjs.com/package/@fgv/ts-utils | Converter} per kind.
+ * @public
+ */
+export declare type Kind = Brand<string, 'Kind'>;
+
+/**
+ /**
+ * Identity codec for the knowledge kind family. A knowledge entity is keyed
+ * by its consumer-supplied `docId`, which is used verbatim as the filename
+ * stem under the flat `knowledge` scope.
+ *
+ * @remarks
+ * - `encode`: scope = `knowledge`, idStem = `docId`, `isVersioned = false`.
+ * - `decode`: brands the stem back to an {@link EntityId}.
+ * - Escaping: the `docId` must match the POSIX portable filename set.
+ * - Layout: `vault/knowledge/<docId>.md`.
+ * @public
+ */
+export declare class KnowledgeIdentityCodec implements IIdentityCodec {
+    /** The fixed scope for every knowledge entity. */
+    static readonly scope: MemoryScopeKey;
+    /** {@inheritDoc IIdentityCodec.encode} */
+    encode(entityId: EntityId): Result<IIdentityCodecResult>;
+    /** {@inheritDoc IIdentityCodec.decode} */
+    decode(scope: MemoryScopeKey, encodedStem: string): Result<EntityId>;
+    /** {@inheritDoc IIdentityCodec.verifyRoundTrip} */
+    verifyRoundTrip(scope: MemoryScopeKey, stem: string): Result<true>;
+}
+
+/**
+ * Last-write-wins write policy for the knowledge kind family. Admission
+ * always accepts (no cap, no cull); updates apply an RFC-7386 merge patch
+ * restricted to the knowledge mutable surface.
+ *
+ * @remarks
+ * **Merge-surface pin (resolves design-lock §5.3's body-vs-envelope muddle).**
+ * The declared `mutableFields` span both axes of a record: `body` is the
+ * per-kind body, while `tags` / `links` / `provenance` / `embeddingRef` live
+ * on the {@link IMemoryEnvelope}. `applyUpdate` projects exactly those fields
+ * — each read from its canonical location — into a single record-level JSON
+ * view, runs the merge over that view, then rebuilds a coherent record. The
+ * identity and transaction-time envelope fields (`id`, `entityId`, `kind`,
+ * `created`, `updated`, `seq`, `contentHash`) are NOT mutable and are
+ * preserved verbatim; the store stamps `updated` / `seq` on write.
+ * @public
+ */
+export declare class KnowledgeLwwPolicy implements IWritePolicy {
+    /**
+     * The knowledge mutable surface: the body plus the envelope metadata a
+     * consumer may revise without minting a new entity.
+     */
+    readonly mutableFields: ReadonlyArray<string>;
+    /**
+     * Knowledge dedups scope-wide: an identical `{ kind, body, links }` triple
+     * anywhere in the `knowledge` scope — even under a different `docId` — is a
+     * no-op. Declared explicitly so the B1 content-dedup behavior (and its tests)
+     * are unchanged by the {@link DedupScope} amendment.
+     */
+    readonly dedupScope: DedupScope;
+    /** Deep-clones the mutable view without RFC-7386 null-deletion semantics. */
+    private readonly _cloneEditor;
+    /** Applies the RFC-7386 merge patch. */
+    private readonly _mergeEditor;
+    private constructor();
+    /**
+     * Family-convention factory. Constructs the shared `JsonEditor` instances
+     * (one for cloning, one for the RFC-7386 merge), both with the template /
+     * conditional / multivalue / reference rules disabled (empty rules array).
+     */
+    static create(): Result<KnowledgeLwwPolicy>;
+    /** {@inheritDoc IWritePolicy.admit} */
+    admit(__incoming: IMemoryRecord<unknown>, __existing: ReadonlyArray<IMemoryRecord<unknown>>): Result<AdmissionDecision>;
+    /** {@inheritDoc IWritePolicy.applyUpdate} */
+    applyUpdate(existing: IMemoryRecord<unknown>, patch: Record<string, unknown>): Result<IMemoryRecord<unknown>>;
+    /**
+     * Reassemble a record from the merged mutable view. `body` / `tags` /
+     * `links` / `provenance` are required and may not be deleted by a patch.
+     * `embeddingRef` is optional: when it is absent from the merged view —
+     * because the existing record never carried it OR a `null` patch deleted it
+     * (RFC-7386) — it is restored as `undefined` (absent), NOT `null`. This keeps
+     * an originally-absent `embeddingRef` from silently flipping to `null` on an
+     * unrelated update, so the field round-trips hash-stably through the store's
+     * content-hash recomputation.
+     */
+    private _rebuild;
+}
+
+/**
+ * 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 declare function limitRecords(records: ReadonlyArray<IMemoryRecord<unknown>>, limit?: number): ReadonlyArray<IMemoryRecord<unknown>>;
+
+/**
+ * The loud-degradation message returned when a link-traversal query supplies no
+ * seed (`linkedFrom` / `linkedTo`).
+ * @public
+ */
+export declare const LINK_TRAVERSAL_NO_SEED_MESSAGE: string;
+
+/**
+ * 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 declare const LINK_TRAVERSAL_UNWIRED_MESSAGE: string;
+
+/**
+ * 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 declare class LinkTraversalRetriever implements IMemoryRetriever {
+    private readonly _index;
+    private constructor();
+    /** Family-convention factory. */
+    static create(index: IMemoryIndex): Result<LinkTraversalRetriever>;
+    /** {@inheritDoc IMemoryRetriever.capabilities} */
+    get capabilities(): IMemoryRetrieverCapabilities;
+    /** {@inheritDoc IMemoryRetriever.retrieve} */
+    retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+    /** Run the bounded, cycle-safe BFS and post-filter the reached records. */
+    private _traverse;
+    /**
+     * 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;
+    /** Outbound neighbors: the targets of every edge on the records with this id. */
+    private _outbound;
+    /** Inbound neighbors: the ids whose edges point AT this id (the backlinks). */
+    private _inbound;
+}
+
+/**
+ * Open-vocabulary link-relation type for an attributed {@link IEdge}.
+ * @public
+ */
+export declare type LinkType = Brand<string, 'LinkType'>;
+
+/**
+ * Identity codec for the long-term-memory (LTM) kind family. An LTM entity is
+ * keyed by its `conversationId`, used verbatim as the filename stem under the
+ * flat `conversations` scope.
+ *
+ * @remarks
+ * - `encode`: scope = `conversations`, idStem = `conversationId`, `isVersioned = false`.
+ * - `decode`: brands the stem back to an {@link EntityId}.
+ * - Escaping: the `conversationId` must match the POSIX portable filename set.
+ * - Layout: `vault/conversations/<conversationId>.md`.
+ *
+ * An LTM file (`conversations/<id>.md`) and the MTM subtree
+ * (`conversations/<id>/turn-N.md`) coexist — a file and a same-named directory
+ * are independent on every supported FileTree backend.
+ * @public
+ */
+export declare class LtmIdentityCodec implements IIdentityCodec {
+    /** The fixed scope for every LTM entity. */
+    static readonly scope: MemoryScopeKey;
+    /** {@inheritDoc IIdentityCodec.encode} */
+    encode(entityId: EntityId): Result<IIdentityCodecResult>;
+    /** {@inheritDoc IIdentityCodec.decode} */
+    decode(scope: MemoryScopeKey, encodedStem: string): Result<EntityId>;
+    /** {@inheritDoc IIdentityCodec.verifyRoundTrip} */
+    verifyRoundTrip(scope: MemoryScopeKey, stem: string): Result<true>;
+}
+
+/**
+ * Bounded-ring write policy for the experience (memory) kind families.
+ * Admission accepts until `maxRecords` is reached, then evicts the oldest
+ * record(s) by `created` ascending (design-lock §5.3); updates apply the same
+ * RFC-7386 merge patch as {@link KnowledgeLwwPolicy}, restricted to the declared
+ * {@link IMemoryCapCullPolicyParams.mutableFields | mutableFields}.
+ *
+ * @remarks
+ * - **Dedup scope.** Declares `dedupScope: 'entity'` — two distinct memory
+ *   entities (e.g. `turn-5` / `turn-9`) with identical `{ kind, body, links }`
+ *   never collapse; only an identical re-put of the SAME entity is a no-op.
+ * - **Eviction boundary.** `admit` only DECIDES (returns the `MemoryId`s to
+ *   evict); the store executes the file deletions and index patches. The
+ *   `existing` cohort the cap counts against is whatever the store supplies to
+ *   `admit`.
+ * @public
+ */
+export declare class MemoryCapCullPolicy implements IWritePolicy {
+    /** {@inheritDoc IWritePolicy.mutableFields} */
+    readonly mutableFields: ReadonlyArray<string>;
+    /** Experience kinds dedup per-entity (see the class remarks). */
+    readonly dedupScope: DedupScope;
+    /** The admission cap; `undefined` = no cap. */
+    private readonly _maxRecords;
+    /** Deep-clones the mutable view without RFC-7386 null-deletion semantics. */
+    private readonly _cloneEditor;
+    /** Applies the RFC-7386 merge patch. */
+    private readonly _mergeEditor;
+    private constructor();
+    /**
+     * Family-convention factory. Constructs the shared `JsonEditor` instances
+     * (one for cloning, one for the RFC-7386 merge) with the same merge config as
+     * {@link KnowledgeLwwPolicy} (`nullAsDelete` true, `arrayMergeBehavior`
+     * `'replace'`, rules disabled).
+     */
+    static create(params: IMemoryCapCullPolicyParams): Result<MemoryCapCullPolicy>;
+    /** {@inheritDoc IWritePolicy.admit} */
+    admit(__incoming: IMemoryRecord<unknown>, existing: ReadonlyArray<IMemoryRecord<unknown>>): Result<AdmissionDecision>;
+    /** {@inheritDoc IWritePolicy.applyUpdate} */
+    applyUpdate(existing: IMemoryRecord<unknown>, patch: Record<string, unknown>): Result<IMemoryRecord<unknown>>;
+    /**
+     * Reassemble a record from the merged mutable view. Only the declared mutable
+     * fields are taken from the merge; undeclared fields are preserved verbatim
+     * from `existing`. A `null` patch that deletes a *declared mutable* required
+     * field (`body` / `tags` / `links` / `provenance`) is an error — a required
+     * field that is NOT declared mutable simply falls through to its `existing.*`
+     * value and is never at risk. `embeddingRef`, when mutable, is restored as
+     * `undefined` (absent) if the merge dropped it — same hash-stable semantics as
+     * {@link KnowledgeLwwPolicy}.
+     */
+    private _rebuild;
+}
+
+/**
+ * Embeds a complete record into a vector for the store's embed-on-write hook.
+ * Async and `Result`-returning, since a real embedder does a network call (cloud
+ * provider) or in-process model inference. The consumer wires this — the core
+ * package never calls an embedding provider directly, staying embedder-agnostic.
+ * @public
+ */
+export declare type MemoryEmbedder = (record: IMemoryRecord<unknown>) => Promise<Result<Float32Array>>;
+
+/**
+ * Stable file-stem identifier for a memory record. Equals the codec-produced
+ * `idStem` and the on-disk filename stem (`verifyFilenameId` enforces the
+ * round-trip).
+ * @public
+ */
+export declare type MemoryId = Brand<string, '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 declare class MemoryIndex implements IMemoryIndex {
+    /** Primary store: `(scope, id)` composite key → indexed entry. */
+    private readonly _byKey;
+    /** kind → set of composite keys. */
+    private readonly _byKind;
+    /** tag → set of composite keys. */
+    private readonly _byTag;
+    /**
+     * 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;
+    private constructor();
+    /** Family-convention factory. */
+    static create(): Result<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;
+    /** {@inheritDoc IMemoryIndex.rebuild} */
+    rebuild(entries: ReadonlyArray<IIndexedMemoryRecord>): Result<number>;
+    /** {@inheritDoc IMemoryIndex.patch} */
+    patch(op: MemoryIndexPatchOp, entry: IIndexedMemoryRecord): Result<IIndexedMemoryRecord>;
+    /** {@inheritDoc IMemoryIndex.entries} */
+    entries(): ReadonlyArray<IIndexedMemoryRecord>;
+    /** {@inheritDoc IMemoryIndex.byKind} */
+    byKind(kind: Kind): ReadonlyArray<IMemoryRecord<unknown>>;
+    /** {@inheritDoc IMemoryIndex.byTag} */
+    byTag(tag: Tag): ReadonlyArray<IMemoryRecord<unknown>>;
+    /** {@inheritDoc IMemoryIndex.byRecency} */
+    byRecency(): ReadonlyArray<IMemoryRecord<unknown>>;
+    /** {@inheritDoc IMemoryIndex.backlinks} */
+    backlinks(target: MemoryId): ReadonlyArray<MemoryId>;
+    /**
+     * 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;
+    /** Insert an entry and register all its derived associations. */
+    private _add;
+    /** Remove the entry at `key` (if present) and all its derived associations. */
+    private _remove;
+    /** Register `sourceId` (keyed by its composite `sourceKey`) as linking at `target`. */
+    private _addBacklink;
+    /** Drop the backlink from `sourceKey` to `target`, removing the target map when empty. */
+    private _removeBacklink;
+    /** Add `member` to the set at `mapKey`, creating the set on first use. */
+    private _addToSetMap;
+    /** Remove `member` from the set at `mapKey`, dropping the set when empty. */
+    private _removeFromSetMap;
+}
+
+/**
+ * The mutation a {@link IMemoryIndex.patch | patch} applies: a record was
+ * written (`'put'`) or removed (`'delete'`).
+ * @public
+ */
+export declare type MemoryIndexPatchOp = 'put' | 'delete';
+
+/**
+ * The outcome of the observed operation.
+ * @public
+ */
+export declare type MemoryObservationOutcome = 'success' | 'failure';
+
+/**
+ * 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 declare type MemoryObservationPhase = 'read' | 'write' | 'delete' | 'retrieve';
+
+/**
+ * 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 declare 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;
+    /**
+     * @param buffer - The pre-constructed backing ring buffer.
+     * @internal
+     */
+    private constructor();
+    /**
+     * 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}.
+     */
+    get lastSeq(): number;
+    /**
+     * The number of records currently retained.
+     */
+    get size(): number;
+    /**
+     * 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.
+     */
+    static create(params?: IMemoryObservationStoreCreateParams): Result<MemoryObservationStore>;
+    /**
+     * {@inheritDoc IMemoryObserver.observe}
+     */
+    observe(record: IMemoryObservationRecord): Promise<Result<unknown>>;
+    /**
+     * Returns retained records, oldest-first, narrowed by the supplied criteria.
+     * @param criteria - {@link IMemoryObservationQuery | AND-combined filter criteria}.
+     * @returns The matching records, oldest-first.
+     */
+    query(criteria?: IMemoryObservationQuery): ReadonlyArray<IMemoryObservationRecord>;
+    /**
+     * Clears all retained records. Does NOT reset
+     * {@link MemoryObservationStore.lastSeq | lastSeq}, so a held `sinceSeq`
+     * cursor never re-sees a sequence number.
+     */
+    clear(): void;
+    /**
+     * Tests a record against the non-`seq`/`limit` criteria (those are applied by
+     * the ring buffer itself).
+     * @internal
+     */
+    private static _matches;
+}
+
+/**
+ * Scope path segment. May be multi-segment (`/`-separated) for kinds whose
+ * codec maps an entity into a sub-tree (e.g. MTM: `conversations/<id>`). The
+ * codec — not this brand — owns filename-safe escaping, so the converter
+ * validates only the non-empty/length/whitespace hygiene shared by every
+ * brand.
+ * @public
+ */
+export declare type MemoryScopeKey = Brand<string, 'MemoryScopeKey'>;
+
+/**
+ * Identity codec for the medium-term-memory (MTM) kind family. An MTM entity is
+ * keyed by the colon-composite `<conversationId>:<turnIndex>` and maps into a
+ * per-conversation subtree.
+ *
+ * @remarks
+ * - `encode`: splits the entity id on `:`; scope =
+ *   `conversations/<conversationId>` (multi-segment), idStem = `turn-<turnIndex>`,
+ *   `isVersioned = false`.
+ * - `decode`: reverses scope `conversations/<id>` + stem `turn-<N>` to the
+ *   composite `<id>:<N>`.
+ * - Escaping: `conversationId` must match the POSIX portable filename set (so it
+ *   contains no `/` or `:`); `turnIndex` must be a non-negative integer string,
+ *   preserved verbatim so the round-trip is exact.
+ * - Layout: `vault/conversations/<conversationId>/turn-<N>.md`. The `/` in the
+ *   scope is handled by the store's multi-segment scope resolver.
+ *
+ * **Verbatim turn index (caller-canonicalization note).** The turn index is
+ * preserved exactly — `conv-1:7` and `conv-1:007` are DISTINCT entities mapping
+ * to distinct files (`turn-7.md` / `turn-007.md`). Verbatim preservation is what
+ * makes the round-trip exact, but it means a caller that formats turn indices
+ * inconsistently (some zero-padded, some not) will silently mint separate
+ * entities. Callers should canonicalize to one form (e.g. no leading zeros).
+ * @public
+ */
+export declare class MtmIdentityCodec implements IIdentityCodec {
+    /** The top-level scope segment under which every MTM subtree lives. */
+    static readonly rootScopeSegment: string;
+    /** The fixed filename-stem prefix for a turn record. */
+    static readonly turnStemPrefix: string;
+    /** A non-negative integer string (the turn index), preserved verbatim. */
+    private static readonly _turnIndexRe;
+    /** {@inheritDoc IIdentityCodec.encode} */
+    encode(entityId: EntityId): Result<IIdentityCodecResult>;
+    /** {@inheritDoc IIdentityCodec.decode} */
+    decode(scope: MemoryScopeKey, encodedStem: string): Result<EntityId>;
+    /** {@inheritDoc IIdentityCodec.verifyRoundTrip} */
+    verifyRoundTrip(scope: MemoryScopeKey, stem: string): Result<true>;
+    /** Validate and extract the `conversationId` from a `conversations/<id>` scope. */
+    private static _conversationIdFromScope;
+    /** Validate and extract the turn-index digits from a `turn-<N>` stem. */
+    private static _turnIndexFromStem;
+    /** Assert a string is a non-negative integer (the turn index). */
+    private static _assertTurnIndex;
+}
+
+/**
+ * The capabilities every non-semantic, non-temporal, non-link v1 retriever
+ * exposes (all three flags `false`).
+ * @public
+ */
+export declare const NON_SEMANTIC_CAPABILITIES: IMemoryRetrieverCapabilities;
+
+/**
+ * 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 declare function parseMemoryFile(raw: string, registry: IBodyConverterRegistry): Result<IMemoryRecord<unknown>>;
+
+/**
+ * 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 declare const provenanceConverter: Converter<IProvenance>;
+
+/**
+ * Origin of a provenance attribution. Open vocabulary: the three named
+ * sources are conventional, but the `(string & {})` arm admits any other
+ * source string without resignature.
+ * @public
+ */
+export declare type ProvenanceSource = 'agent' | 'host-ingest' | 'human' | (string & {});
+
+/**
+ * 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 declare type QueryEmbedder = (text: string) => Promise<Result<Float32Array>>;
+
+/**
+ * Recency comparator: most-recently-updated first, with a `seq` tiebreak so
+ * equal-`updated` records sort deterministically. Mirrors the B1 index ordering.
+ * @public
+ */
+export declare function recencyCompare(a: IMemoryRecord<unknown>, b: IMemoryRecord<unknown>): number;
+
+/**
+ * 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 declare class RecencyRetriever implements IMemoryRetriever {
+    private readonly _index;
+    private constructor();
+    /** {@inheritDoc IMemoryRetriever.capabilities} */
+    get capabilities(): IMemoryRetrieverCapabilities;
+    /** Family-convention factory. */
+    static create(index: IMemoryIndex): Result<RecencyRetriever>;
+    /** {@inheritDoc IMemoryRetriever.retrieve} */
+    retrieve(query: IMemoryQuery): Promise<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 declare class ScoreUnionMergeStrategy implements IMergeStrategy {
+    private constructor();
+    /** Family-convention factory. */
+    static create(): Result<ScoreUnionMergeStrategy>;
+    /** {@inheritDoc IMergeStrategy.merge} */
+    merge(resultSets: ReadonlyArray<ReadonlyArray<IMemoryRecord<unknown>>>): Result<ReadonlyArray<IMemoryRecord<unknown>>>;
+}
+
+/**
+ * Apply the shared scope / kind / tag / predicate pre-filter to a set of indexed
+ * entries, returning the surviving records (unordered, unlimited).
+ * @public
+ */
+export declare function selectByQuery(entries: ReadonlyArray<IIndexedMemoryRecord>, query: IMemoryQuery): IMemoryRecord<unknown>[];
+
+/**
+ * The loud-degradation message a retriever returns when `query.semantic` is set
+ * but no {@link IVectorIndex} is wired.
+ * @public
+ */
+export declare const SEMANTIC_UNWIRED_MESSAGE: string;
+
+/**
+ * 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 declare class SemanticRetriever implements IMemoryRetriever {
+    private readonly _index;
+    private readonly _backend;
+    private constructor();
+    /** {@inheritDoc IMemoryRetriever.capabilities} */
+    get capabilities(): IMemoryRetrieverCapabilities;
+    /** Family-convention factory. */
+    static create(params: ISemanticRetrieverCreateParams): Result<SemanticRetriever>;
+    /** {@inheritDoc IMemoryRetriever.retrieve} */
+    retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+    /**
+     * 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 _callBackend;
+}
+
+/**
+ * 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 declare function serializeMemoryFile(envelope: IMemoryEnvelope, body: string): Result<string>;
+
+/**
+ * Split a `---\n<yaml>\n---\n<body>` memory file into its frontmatter and
+ * body parts. Pure string handling — no external dependency.
+ * @public
+ */
+export declare function splitFrontmatter(raw: string): Result<IMemoryFileParts>;
+
+/**
+ * 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 declare class StructuredFilterRetriever implements IMemoryRetriever {
+    private readonly _index;
+    private constructor();
+    /** {@inheritDoc IMemoryRetriever.capabilities} */
+    get capabilities(): IMemoryRetrieverCapabilities;
+    /** Family-convention factory. */
+    static create(index: IMemoryIndex): Result<StructuredFilterRetriever>;
+    /** {@inheritDoc IMemoryRetriever.retrieve} */
+    retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+}
+
+/**
+ * Open-vocabulary tag label.
+ * @public
+ */
+export declare type Tag = Brand<string, 'Tag'>;
+
+/**
+ * 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 declare class TagRetriever implements IMemoryRetriever {
+    private readonly _index;
+    private constructor();
+    /** {@inheritDoc IMemoryRetriever.capabilities} */
+    get capabilities(): IMemoryRetrieverCapabilities;
+    /** Family-convention factory. */
+    static create(index: IMemoryIndex): Result<TagRetriever>;
+    /** {@inheritDoc IMemoryRetriever.retrieve} */
+    retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+}
+
+/**
+ * Converter for the optional {@link ITemporalBlock}.
+ * @public
+ */
+export declare const temporalConverter: Converter<ITemporalBlock>;
+
+/**
+ * Build the loud-degradation message a retriever returns when `query.asOf` is
+ * set but no temporal index is wired.
+ * @public
+ */
+export declare function temporalUnwiredMessage(kind?: Kind): string;
+
+export { }