@fgv/ts-agent-memory 5.1.0-39 → 5.1.0-41

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

@@ -251,6 +251,26 @@ export declare function defaultMemoryScopeEncoding(scope: MemoryScopeKey): Resul
  */
 export declare const edgeConverter: Converter<IEdge>;
 
+/**
+ * Converter for a scope-qualified {@link IEdgeTarget}. Both `scope` and `id`
+ * are required — the whole point of the scoped target is that a bare id is
+ * ambiguous across scopes.
+ * @public
+ */
+export declare const edgeTargetConverter: Converter<IEdgeTarget>;
+
+/**
+ * The canonical composite-key string for an {@link IEdgeTarget}: scope + id,
+ * NUL-separated. NUL is excluded from both components (scope segments are
+ * filename-safe; {@link MemoryId} is portable-filename-safe), so it is a
+ * collision-proof separator. This is the ONE canonicalization every consumer
+ * that keys on a scoped target uses — the backlink index, the cycle guard, and
+ * the ingest edge-validation path all route through it so their notions of
+ * "same target" cannot drift.
+ * @public
+ */
+export declare function edgeTargetKey(target: IEdgeTarget): string;
+
 /**
  * Consumer-supplied domain key. The stable entity identity across versions;
  * the package never mints identity. Equals {@link MemoryId} for non-temporal
@@ -292,6 +312,7 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
     private readonly _registry;
     private readonly _writePolicies;
     private readonly _codecs;
+    private readonly _rankProjectors;
     private readonly _defaultCodec;
     private readonly _defaultPolicy;
     private readonly _scopeEncoding;
@@ -334,6 +355,10 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
     getById(scope: MemoryScopeKey, id: MemoryId): Promise<Result<IMemoryRecord<unknown> | undefined>>;
     /** {@inheritDoc IMemoryStore.list} */
     list(filter?: IMemoryStoreListFilter): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+    /** {@inheritDoc IMemoryStore.listScoped} */
+    listScoped(): Promise<Result<ReadonlyArray<IScopedMemoryRecord>>>;
+    /** {@inheritDoc IMemoryStore.asRecordSource} */
+    asRecordSource(): IMemoryRecordSource;
     /**
      * Collapse temporal records to the single version valid at `asOf` per entity;
      * non-temporal records are timeless and pass through unchanged (valid-time
@@ -413,7 +438,12 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
      * `accept` / `reject` decisions evict nothing.
      */
     private _applyEvictions;
-    /** Best-effort vector removal for each evicted record (never fails the put). */
+    /**
+     * Best-effort vector removal for each evicted record (never fails the put).
+     * Every evicted record is in the same `scope` as the incoming write (the
+     * cull-oldest cohort is the incoming record's `(scope, kind)` cohort), so that
+     * scope qualifies each removal target.
+     */
     private _removeEvictedVectors;
     /**
      * Run a consumer-supplied vector hook, normalizing a thrown/rejected hook into a
@@ -544,6 +574,19 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
      */
     private _isMutableMetadataUnchanged;
     private _contentHash;
+    /**
+     * Stamp the store-computed {@link IMemoryEnvelope.rank} onto a fully-built,
+     * fully-stamped record by running the kind's registered {@link RankProjector}.
+     * Runs on the SAME resolved (post-merge) record whose `contentHash` was just
+     * computed, so `rank` is always consistent with the current body — no separate
+     * write path and no consumer write-discipline rule. A no-op pass-through
+     * (byte-identical record) when the kind has no projector — the additive,
+     * zero-overhead-when-unwired default. The projector is a host callback: a throw
+     * is logged at `warn` and the record is stamped with NO `rank` (the field is
+     * explicitly cleared, so a throw on an update drops a now-stale prior rank rather
+     * than preserving it), so a ranking bug never loses an authoritative write.
+     */
+    private _stampRank;
     private _codecFor;
     private _policyFor;
     /**
@@ -720,8 +763,8 @@ export declare interface IBodyConverterRegistry {
  * @public
  */
 export declare interface ICandidateEdge {
-    /** The reference id (codec `idStem`) of the candidate the edge originates from. */
-    readonly source: MemoryId;
+    /** The scope-qualified reference (codec `(scope, idStem)`) of the candidate the edge originates from. */
+    readonly source: IEdgeTarget;
     /** The attributed edge (type / target / optional confidence / provenance). */
     readonly edge: IEdge;
 }
@@ -792,31 +835,47 @@ export declare interface ICreateMemoryToolsParams {
      * {@link MemoryId} is used.
      */
     readonly handleFor?: (record: IMemoryRecord<unknown>) => string;
+    /**
+     * Optional host projector mapping a record (and the requested detail tier) to
+     * its agent-visible {@link IMemoryToolResultItem}. When supplied, every
+     * `memory_search` / `memory_context` / `memory_read` result item is produced by
+     * this callback — the host owns how much of the body a `'gist'` vs `'full'`
+     * result carries, so it can bound the default (`'gist'`) path.
+     *
+     * When absent, the built-in default projection is used (full body plus the
+     * {@link ICreateMemoryToolsParams.handleFor | handleFor} handle), which ignores
+     * the detail tier — behavior is byte-identical to a build with no projector.
+     *
+     * The callback is guarded exactly like `handleFor`: a throw degrades to the
+     * default full-body projection for that item rather than failing the whole
+     * search.
+     */
+    readonly projectItem?: (record: IMemoryRecord<unknown>, detail: MemoryDetailTier) => IMemoryToolResultItem;
 }
 
 /**
- * A directed edge in the link graph the cycle guard reasons over: `source` links
- * to `target` under relation `type`.
+ * A directed edge in the link graph the cycle guard reasons over: scope-qualified
+ * `source` links to scope-qualified `target` under relation `type`.
  * @public
  */
 export declare interface ICycleGuardEdge {
-    readonly source: MemoryId;
-    readonly target: MemoryId;
+    readonly source: IEdgeTarget;
+    readonly target: IEdgeTarget;
     readonly type: LinkType;
 }
 
 /**
  * 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')`).
+ * scope-qualified {@link IEdgeTarget | target}, 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;
+    /** The scope-qualified address of the linked-to record. */
+    readonly target: IEdgeTarget;
     /** Optional confidence in `[0, 1]`. */
     readonly confidence?: number;
     /** Optional structured provenance for the link itself. */
@@ -830,6 +889,23 @@ export declare interface IEdge {
     readonly invalid_at?: number | null;
 }
 
+/**
+ * The physical address of a linked-to record: the `(scope, id)` pair that
+ * uniquely identifies it. Both components are required because a bare
+ * {@link MemoryId} is NOT unique across scopes — per-scope codecs (e.g. the
+ * medium-term codec's `turn-<n>` stems) legally mint the same stem under
+ * different scopes, so an edge that carried only the id would be ambiguous.
+ * `(scope, id)` matches the store's `getById(scope, id)` addressing and the
+ * index's composite primary key.
+ * @public
+ */
+export declare interface IEdgeTarget {
+    /** The scope the target record lives under. */
+    readonly scope: MemoryScopeKey;
+    /** The target record's stable file-stem id (unique WITHIN {@link IEdgeTarget.scope}). */
+    readonly id: MemoryId;
+}
+
 /**
  * A near-duplicate candidate surfaced to the {@link IEntityResolver} by stage-4
  * layer-2 similarity search: an existing record whose embedding is within the
@@ -837,8 +913,14 @@ export declare interface IEdge {
  * @public
  */
 export declare interface IEntityResolutionCandidate {
-    /** The existing record's id. */
-    readonly id: MemoryId;
+    /**
+     * The existing record's scope-qualified `(scope, id)` address. Scope-qualified
+     * (not a bare {@link MemoryId}) because per-scope codecs legally mint the same
+     * stem under different scopes — the {@link ResolutionVerdict} target the resolver
+     * returns must round-trip this exact address so the write binds the intended
+     * record.
+     */
+    readonly target: IEdgeTarget;
     /** The existing record. */
     readonly record: IMemoryRecord<unknown>;
     /** The backend similarity score (higher = more similar). */
@@ -891,6 +973,19 @@ export declare interface IFileTreeMemoryStoreCreateParams {
     readonly writePolicies?: ReadonlyMap<Kind, IWritePolicy>;
     /** Per-kind identity codecs. */
     readonly codecs?: ReadonlyMap<Kind, IIdentityCodec>;
+    /**
+     * Optional per-kind host projector map. When a kind has an entry, the store
+     * runs the projector on the fully-resolved (post-merge) record on every put
+     * AND every update — in the same pass that recomputes `contentHash` — and
+     * stamps the numeric result into {@link IMemoryEnvelope.rank}, which the index's
+     * rank view and `orderBy: 'rank'` retrieval sort by (descending, absent last).
+     * Absent for a kind → that kind's records carry no `rank`. Purely additive and
+     * zero-overhead when unwired: an absent map leaves every write byte-identical.
+     * The projector is a host callback — a throw is logged at `warn` and the record
+     * is stamped with no `rank`, never failing the write (mirrors the store's other
+     * guard-host-callbacks conventions).
+     */
+    readonly rankProjectors?: ReadonlyMap<Kind, RankProjector>;
     /** Default codec for kinds without an explicit entry. */
     readonly defaultCodec?: IIdentityCodec;
     /** Scope encoding. Defaults to {@link defaultMemoryScopeEncoding}. */
@@ -1054,12 +1149,15 @@ export declare interface IIngestItem {
      */
     readonly content: unknown;
     /**
-     * Optional back-link to the memory record this item was derived from (e.g. the
-     * MTM turn an extracted fact came from). When present, fgv stamps it as
-     * {@link IProvenance.derivedFrom | provenance.derivedFrom} on every record
-     * ingested from this item (stage 6) — the cross-kind provenance spine.
+     * Optional scope-qualified back-link to the memory record this item was derived
+     * from (e.g. the MTM turn an extracted fact came from). When present, fgv stamps
+     * it as {@link IProvenance.derivedFrom | provenance.derivedFrom} on every record
+     * ingested from this item (stage 6) — the cross-kind provenance spine. A
+     * scope-qualified {@link IEdgeTarget} (not a bare {@link MemoryId}) because
+     * per-scope codecs legally reuse a stem across scopes, so a bare id would be
+     * ambiguous.
      */
-    readonly sourceId?: MemoryId;
+    readonly sourceId?: IEdgeTarget;
     /** Optional opaque metadata carried alongside the item; never interpreted by fgv. */
     readonly metadata?: Record<string, unknown>;
 }
@@ -1161,6 +1259,15 @@ export declare interface IMemoryEnvelope {
      * an exact match is a no-op upsert that returns the existing record.
      */
     readonly contentHash: string;
+    /**
+     * Store-computed host-defined ordering value, produced by the kind's
+     * {@link RankProjector} on every put/update and stamped into the envelope in
+     * the same pass that recomputes {@link IMemoryEnvelope.contentHash | contentHash}.
+     * Absent when the kind has no registered projector (or the projector threw on
+     * this record). Ordered retrieval (`orderBy: 'rank'`) and the index's rank view
+     * sort by this value descending, placing records with an absent `rank` last.
+     */
+    readonly rank?: number;
     /** Structured provenance (never a flat enum). */
     readonly provenance: IProvenance;
     /** Bi-temporal validity. Present only on temporal kinds. */
@@ -1218,10 +1325,20 @@ export declare interface IMemoryIndex {
     /** 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.
+     * All records ordered by store-computed {@link IMemoryEnvelope.rank} descending,
+     * with recency (most-recently-updated, then `seq`) as a tiebreak. Records with
+     * an absent `rank` sort LAST (after every ranked record), then by recency among
+     * themselves. Serves a bounded top-M ({@link IMemoryEnvelope.rank}-ordered) page
+     * from the in-memory index with no full-vault (filesystem) scan.
      */
-    backlinks(target: MemoryId): ReadonlyArray<MemoryId>;
+    byRank(): ReadonlyArray<IMemoryRecord<unknown>>;
+    /**
+     * The scope-qualified sources of records whose `links` point AT `target`
+     * (inbound edges), keyed on the target's `(scope, id)` address. The seed map
+     * for B2 link-traversal; results are {@link IEdgeTarget}s so a caller can feed
+     * them straight back in as further traversal seeds.
+     */
+    backlinks(target: IEdgeTarget): ReadonlyArray<IEdgeTarget>;
 }
 
 /**
@@ -1409,12 +1526,24 @@ export declare interface IMemoryQuery {
     readonly scope?: MemoryScopeKey;
     /** Restrict to records carrying this tag (exact match). */
     readonly tag?: Tag;
-    /** Restrict to records of this kind. */
+    /**
+     * Restrict to records of this kind — the single-kind shorthand for
+     * {@link IMemoryQuery.kinds | kinds}. When both are set they compose as AND
+     * (the record's kind must satisfy both), so `kind` must itself be a member of
+     * `kinds` for anything to match.
+     */
     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;
+    /**
+     * Restrict to records in ANY of these kinds — the general (multi-kind) form of
+     * {@link IMemoryQuery.kind | kind}. Absent → no kind-set constraint (today's
+     * behavior). An explicit empty array `[]` matches NOTHING (mirroring the
+     * non-positive-`limit` "explicit empty" convention), never "match all".
+     */
+    readonly kinds?: ReadonlyArray<Kind>;
+    /** Restrict to records linked FROM this scope-qualified seed (outbound). */
+    readonly linkedFrom?: IEdgeTarget;
+    /** Restrict to records linked TO this scope-qualified seed (inbound / backlinks). */
+    readonly linkedTo?: IEdgeTarget;
     /** BFS hop count for link traversal. Default: 1. */
     readonly hops?: number;
     /**
@@ -1431,8 +1560,32 @@ export declare interface IMemoryQuery {
      * `Result.fail` — never a silent empty.
      */
     readonly asOf?: number;
+    /**
+     * Ordering for the result set. `'recency'` (the default when absent — today's
+     * exact behavior) orders most-recently-updated first; `'rank'` orders by the
+     * store-computed {@link IMemoryEnvelope.rank} descending (records with an absent
+     * `rank` last), with recency as the tiebreak. Combined with `{ limit, offset }`
+     * this yields a bounded top-M rank-ordered page with no full-vault scan.
+     *
+     * @remarks
+     * `orderBy` governs the ordered non-semantic retrievers (recency / tag /
+     * structured-filter / link-traversal) and the {@link HybridRetriever}'s
+     * post-merge ordering. The {@link SemanticRetriever} is the sole exception: it
+     * preserves its native vector-similarity order regardless of `orderBy` —
+     * re-sorting semantic hits by `rank` would discard the similarity ranking that
+     * is the whole point of that path; a consumer that wants rank ordering uses a
+     * non-semantic query.
+     */
+    readonly orderBy?: 'recency' | 'rank';
     /** Maximum records to return. Applied after all other filters. */
     readonly limit?: number;
+    /**
+     * Records to skip after ordering, before `limit` — so `{ offset, limit }` is a
+     * stable page window over the ordered result set. Default 0. A non-positive or
+     * absent offset is today's behavior (no skip); an offset past the end yields an
+     * empty page, never a throw.
+     */
+    readonly offset?: number;
     /** Arbitrary predicate applied after the scope / kind / tag pre-filter. */
     readonly filter?: (record: IMemoryRecord<unknown>) => boolean;
 }
@@ -1453,16 +1606,17 @@ export declare interface IMemoryRecord<TBody = unknown> {
 
 /**
  * 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).
+ * re-embed an entire vault. Each entry carries the record's scope-qualified
+ * address (see {@link IScopedMemoryRecord}) so the rebuild keys the vector index
+ * exactly as the incremental embed-on-write path does. A consumer backs this with
+ * the store's scoped index — the vector packlet does not import 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>>>>;
+    /** List every record in the vault, each paired with its scoped address. */
+    list(): Promise<Result<ReadonlyArray<IScopedMemoryRecord>>>;
 }
 
 /**
@@ -1519,6 +1673,24 @@ export declare interface IMemoryStore {
      * List records, filtered in-memory over the derived index.
      */
     list(filter?: IMemoryStoreListFilter): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+    /**
+     * List EVERY record in the vault, each paired with its scope-qualified
+     * `(scope, id)` address — the projection {@link IMemoryRecordSource} requires.
+     * Unlike {@link IMemoryStore.list | list}, it takes no filter (whole-vault) and
+     * returns {@link IScopedMemoryRecord}s so a re-index keys each entry on the same
+     * scoped target the incremental embed-on-write path uses. Two records that share
+     * a filename stem across scopes appear as distinct entries.
+     */
+    listScoped(): Promise<Result<ReadonlyArray<IScopedMemoryRecord>>>;
+    /**
+     * Adapt this store to the {@link IMemoryRecordSource} seam so it can drive
+     * {@link IVectorIndex} rebuilds (e.g. `InMemoryCosineIndex.rebuild`). The
+     * returned source's `list()` delegates to {@link IMemoryStore.listScoped}. The
+     * store cannot implement {@link IMemoryRecordSource} directly because its
+     * `list(filter?)` returns bare records (the ergonomic query surface) while the
+     * seam's `list()` returns scope-qualified records.
+     */
+    asRecordSource(): IMemoryRecordSource;
     /**
      * Write a record. Validates the body, computes a content hash, deduplicates
      * (scope-wide, before policy), applies the kind's {@link IWritePolicy}, stamps
@@ -1649,6 +1821,11 @@ export declare type IngestDisposition = 'written' | 'deduped' | 'merged';
  * @public
  */
 export declare class InMemoryCosineIndex implements IVectorIndex {
+    /**
+     * Stored embeddings keyed by the canonical {@link edgeTargetKey} of the
+     * record's scope-qualified address, so two records that share a filename stem
+     * across scopes occupy distinct entries and never overwrite each other.
+     */
     private readonly _vectors;
     /** The dimension of every stored vector; `undefined` until the first `add`. */
     private _dimension;
@@ -1658,9 +1835,9 @@ export declare class InMemoryCosineIndex implements IVectorIndex {
     /** Family-convention factory. */
     static create(): Result<InMemoryCosineIndex>;
     /** {@inheritDoc IVectorIndex.add} */
-    add(id: MemoryId, vector: Float32Array): Promise<Result<string>>;
+    add(target: IEdgeTarget, vector: Float32Array): Promise<Result<string>>;
     /** {@inheritDoc IVectorIndex.remove} */
-    remove(id: MemoryId): Promise<Result<MemoryId>>;
+    remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>>;
     /** {@inheritDoc IVectorIndex.query} */
     query(vector: Float32Array, topK: number): Promise<Result<ReadonlyArray<IVectorQueryHit>>>;
     /**
@@ -1673,8 +1850,7 @@ export declare class InMemoryCosineIndex implements IVectorIndex {
      * 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 source - The scope-qualified record source to re-embed.
      * @param embed - The embedder applied to each record.
      */
     rebuild(source: IMemoryRecordSource, embed: MemoryEmbedder): Promise<Result<number>>;
@@ -1707,8 +1883,14 @@ export declare interface IProvenance {
     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;
+    /**
+     * Scope-qualified back-link to the source record. Enables the cross-kind
+     * provenance spine. A scope-qualified {@link IEdgeTarget} (not a bare
+     * {@link MemoryId}) because per-scope codecs (e.g. the MTM codec's `turn-<n>`
+     * stems) legally reuse a stem across scopes, so a bare id would be ambiguous —
+     * the same reason {@link IEdge.target} is scope-qualified.
+     */
+    readonly derivedFrom?: IEdgeTarget;
     /** Opaque extension payload — consumer-owned, never interpreted by the store. */
     readonly [key: string]: unknown;
 }
@@ -1721,8 +1903,8 @@ export declare interface IProvenance {
 export declare interface IRelationCandidate {
     /** The candidate about to be written. */
     readonly candidate: ICandidateRecord;
-    /** Its resolved reference id (codec `idStem` — the stable entity reference). */
-    readonly id: MemoryId;
+    /** Its resolved scope-qualified reference (codec `(scope, idStem)` — the stable entity address). */
+    readonly id: IEdgeTarget;
 }
 
 /**
@@ -1755,6 +1937,21 @@ export declare interface IRelationExtractor {
     relate(context: IRelationContext): Promise<Result<ReadonlyArray<ICandidateEdge>>>;
 }
 
+/**
+ * A record paired with its scope-qualified {@link IEdgeTarget | address}, as
+ * yielded by {@link IMemoryRecordSource.list}. The address is required because
+ * {@link InMemoryCosineIndex.rebuild} keys each re-embedded entry on the
+ * scope-qualified target, not a bare {@link MemoryId} — two records that share a
+ * filename stem across scopes must not collide when the whole vault is re-indexed.
+ * @public
+ */
+export declare interface IScopedMemoryRecord {
+    /** The record's scope-qualified `(scope, id)` address. */
+    readonly target: IEdgeTarget;
+    /** The record itself, passed to the embedder. */
+    readonly record: IMemoryRecord<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
@@ -1884,16 +2081,19 @@ export declare interface ITemporalVersionAddress {
  */
 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 (or replace) the embedding for the scope-qualified `target`. Returns the
+     * opaque {@link IMemoryEnvelope.embeddingRef | embeddingRef} the store stamps
+     * onto the envelope so a later read knows the record is embedded. Keying on the
+     * `(scope, id)` address (not a bare id) is load-bearing: two records that share
+     * a filename stem across scopes must not clobber each other's embedding.
      */
-    add(id: MemoryId, vector: Float32Array): Promise<Result<string>>;
+    add(target: IEdgeTarget, 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 the embedding for the scope-qualified `target`. Returns the removed
+     * target. Idempotent — removing a target with no embedding still succeeds
+     * (returns the target).
      */
-    remove(id: MemoryId): Promise<Result<MemoryId>>;
+    remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>>;
     /**
      * Return the `topK` nearest records to `vector`, in descending score order.
      */
@@ -1901,14 +2101,22 @@ export declare interface IVectorIndex {
 }
 
 /**
- * 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.
+ * A single hit returned by {@link IVectorIndex.query}: the matched record's
+ * scope-qualified {@link IEdgeTarget | address} and the backend's similarity
+ * score (higher = more similar; the exact scale is backend-defined). Hits are
+ * returned in descending score order.
+ *
+ * @remarks
+ * The address is a `(scope, id)` pair, NOT a bare {@link MemoryId} — per-scope
+ * codecs (e.g. the medium-term codec's `turn-<n>` stems) legally mint the same
+ * stem under different scopes, so a bare id could not disambiguate two records
+ * that share a stem. The caller re-resolves the hit against the record index by
+ * the same scoped address.
  * @public
  */
 export declare interface IVectorQueryHit {
-    /** The id of the matched record. */
-    readonly id: MemoryId;
+    /** The scope-qualified address of the matched record. */
+    readonly target: IEdgeTarget;
     /** Backend similarity score; higher is more similar. */
     readonly score: number;
 }
@@ -2056,13 +2264,21 @@ export declare class KnowledgeLwwPolicy implements IWritePolicy {
 }
 
 /**
- * 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`.
+ * Apply the `{ offset, limit }` page window to an ordered record set. Applied
+ * last, after ordering, so it always takes a stable window of the ordered
+ * result. `offset` is applied first (records to skip), then `limit` (top-N of
+ * the remainder).
+ *
+ * @remarks
+ * Both bounds are public query input and are guarded against non-positive
+ * values slipping into `slice`:
+ * - `offset` absent or non-positive → no skip (today's behavior). An offset past
+ *   the end yields an empty page rather than a throw.
+ * - `limit` absent → no truncation; a non-positive `limit` means "no records"
+ *   and returns an empty array.
  * @public
  */
-export declare function limitRecords(records: ReadonlyArray<IMemoryRecord<unknown>>, limit?: number): ReadonlyArray<IMemoryRecord<unknown>>;
+export declare function limitRecords(records: ReadonlyArray<IMemoryRecord<unknown>>, limit?: number, offset?: number): ReadonlyArray<IMemoryRecord<unknown>>;
 
 /**
  * The loud-degradation message returned when a link-traversal query supplies no
@@ -2080,20 +2296,23 @@ export declare const LINK_TRAVERSAL_NO_SEED_MESSAGE: string;
 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.
+ * Breadth-first link-traversal retriever. From a scope-qualified
+ * {@link IEdgeTarget} seed 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.
+ * - **Scope-qualified nodes.** Every graph node is an {@link IEdgeTarget}
+ *   `(scope, id)` pair, so following an edge to `turn-3` reaches ONLY the record
+ *   in the edge's own scope — never a same-stem record in another scope.
  * - **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.
+ *   single hop) and a visited-set guard. Nodes are canonicalized to their
+ *   `(scope, id)` string via {@link edgeTargetKey}, 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 node 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
@@ -2110,23 +2329,15 @@ export declare class LinkTraversalRetriever implements IMemoryRetriever {
     /** 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. */
+     * Group the index's entries by their scope-qualified {@link edgeTargetKey}
+     * `(scope, id)` composite. Each composite is the index's primary key, so it maps
+     * to exactly one entry — two records that reuse a filename stem across scopes
+     * (e.g. `turn-0` in two conversations) get distinct keys and never collide.
+     */
+    private _indexByKey;
+    /** Outbound neighbors: the scope-qualified targets of every edge on the record at `node`. */
     private _outbound;
-    /** Inbound neighbors: the ids whose edges point AT this id (the backlinks). */
+    /** Inbound neighbors: the scope-qualified sources whose edges point AT `node` (the backlinks). */
     private _inbound;
 }
 
@@ -2216,6 +2427,15 @@ export declare class MemoryCapCullPolicy implements IWritePolicy {
     private _rebuild;
 }
 
+/**
+ * The detail tier a `memory_search` / `memory_context` result is projected at.
+ * `'gist'` is the default (bounded) path; `'full'` is opt-in. Only meaningful
+ * when a host {@link ICreateMemoryToolsParams.projectItem | projectItem} is
+ * supplied — the built-in default projection returns the full body regardless.
+ * @public
+ */
+export declare type MemoryDetailTier = 'gist' | 'full';
+
 /**
  * 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
@@ -2248,10 +2468,13 @@ export declare class MemoryIndex implements IMemoryIndex {
     /** 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.
+     * canonical target key (`edgeTargetKey`) → (source composite key → source
+     * {@link IEdgeTarget}). The OUTER map is keyed on the scope-qualified target's
+     * canonical `(scope, id)` string — NOT the target's bare id — so an edge to
+     * `turn-3` in one conversation is tracked separately from `turn-3` in another.
+     * The INNER map is keyed by the source's `(scope, id)` composite so two distinct
+     * source records that share an id across scopes are tracked independently and
+     * removing one never drops the other's edge.
      */
     private readonly _backlinks;
     private constructor();
@@ -2276,19 +2499,38 @@ export declare class MemoryIndex implements IMemoryIndex {
     byTag(tag: Tag): ReadonlyArray<IMemoryRecord<unknown>>;
     /** {@inheritDoc IMemoryIndex.byRecency} */
     byRecency(): ReadonlyArray<IMemoryRecord<unknown>>;
+    /** {@inheritDoc IMemoryIndex.byRank} */
+    byRank(): ReadonlyArray<IMemoryRecord<unknown>>;
     /** {@inheritDoc IMemoryIndex.backlinks} */
-    backlinks(target: MemoryId): ReadonlyArray<MemoryId>;
+    backlinks(target: IEdgeTarget): ReadonlyArray<IEdgeTarget>;
     /**
      * 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;
+    /**
+     * Resolve a set of composite keys to their records, ordered by
+     * {@link IMemoryEnvelope.rank} descending with recency (`updated`, then `seq`)
+     * as the tiebreak. Records with an absent `rank` sort LAST, then by recency
+     * among themselves. Computed on call (mirrors {@link MemoryIndex._recencyOrdered}) —
+     * no incremental rank-ordered view is maintained, matching the recency view's
+     * approach; the sort is over the in-memory index, never a filesystem walk.
+     */
+    private _rankOrdered;
+    /**
+     * Rank-descending comparator with an absent-`rank`-last rule and a recency
+     * (`updated`, then `seq`) tiebreak. Duplicated from the retrieve packlet's
+     * `rankCompare` deliberately: the index must not depend on `retrieve` (that
+     * package depends on the index), mirroring how `_recencyOrdered` inlines the
+     * recency ordering rather than importing `recencyCompare`.
+     */
+    private static _compareByRank;
     /** 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`. */
+    /** Register `source` (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;
@@ -2382,7 +2624,8 @@ export declare class MemoryIngestOrchestrator implements IMemoryIngestOrchestrat
     private _relate;
     /**
      * Validate stage-5 edges: each `source` must be a candidate being written; each
-     * `target` must resolve to a sibling candidate or an existing store record.
+     * `target` must resolve to a sibling candidate or an existing store record. All
+     * matching is on the canonical scope-qualified address.
      */
     private _validateEdges;
     /** Stage 6 — stamp provenance + edges, admit through the store, record the outcome. */
@@ -2397,10 +2640,23 @@ export declare class MemoryIngestOrchestrator implements IMemoryIngestOrchestrat
     private _resolveAddress;
     /** Run a host hook, normalizing a thrown/rejected hook into a Failure (never throws across the seam). */
     private _capture;
-    /** Index a record snapshot by id (last write wins on an id collision across scopes). */
-    private static _indexById;
-    /** Every existing outbound edge in the snapshot, as cycle-guard edges. */
+    /**
+     * Every existing outbound edge in the snapshot, as cycle-guard edges. The
+     * source is the record's own scope-qualified address (already resolved by
+     * {@link MemoryIngestOrchestrator._scopeRecords}); the target is the edge's
+     * own scoped target. Both ends are scoped so the guard never conflates a stem
+     * shared across scopes into one graph node.
+     */
     private static _existingEdges;
+    /**
+     * Resolve every snapshot record's scope-qualified `(scope, id)` address via its
+     * registered codec. Fails loudly if a record's kind has no resolvable codec —
+     * the edge path cannot place an un-scopeable record in the graph, and a missing
+     * codec for a stored kind is a real misconfiguration, not something to paper over.
+     */
+    private _scopeRecords;
+    /** Human-readable `scope/id` rendering of a scoped target for edge-validation diagnostics. */
+    private static _formatTarget;
     /** A provisional record for embedding a candidate (placeholder txn-time fields). */
     private static _provisionalRecord;
     /** Require a candidate body to be a string (the store persists only string bodies). */
@@ -2592,6 +2848,14 @@ export declare class MtmIdentityCodec implements IIdentityCodec {
  */
 export declare const NON_SEMANTIC_CAPABILITIES: IMemoryRetrieverCapabilities;
 
+/**
+ * Select the record comparator for a query's {@link IMemoryQuery.orderBy | orderBy}
+ * axis: {@link rankCompare} for `'rank'`, {@link recencyCompare} otherwise (the
+ * default, byte-identical to the pre-`orderBy` behavior).
+ * @public
+ */
+export declare function orderingCompare(orderBy?: IMemoryQuery['orderBy']): (a: IMemoryRecord<unknown>, b: IMemoryRecord<unknown>) => number;
+
 /**
  * Parse a complete memory file into a typed {@link IMemoryRecord}. Splits the
  * frontmatter, validates the envelope, and dispatches the body through the
@@ -2623,6 +2887,27 @@ export declare type ProvenanceSource = 'agent' | 'host-ingest' | 'human' | (stri
  */
 export declare type QueryEmbedder = (text: string) => Promise<Result<Float32Array>>;
 
+/**
+ * Rank comparator: store-computed {@link IMemoryEnvelope.rank} descending, with
+ * {@link recencyCompare} as the tiebreak. Records with an absent `rank` sort LAST
+ * (after every ranked record), then by recency among themselves. Mirrors the
+ * index's rank-view ordering.
+ * @public
+ */
+export declare function rankCompare(a: IMemoryRecord<unknown>, b: IMemoryRecord<unknown>): number;
+
+/**
+ * A per-kind host projection from a fully-resolved (post-merge) memory record
+ * to a numeric ordering value. Registered per kind at store construction (see
+ * `rankProjectors`); the store runs it on every put/update over the same
+ * resolved record whose `contentHash` it computes, stamping the result into
+ * {@link IMemoryEnvelope.rank}. The store never interprets the body — the host
+ * owns what the number means. A projector that throws is treated as "no rank
+ * for this record" (logged at `warn`), never failing the write.
+ * @public
+ */
+export declare type RankProjector = (record: IMemoryRecord<unknown>) => number;
+
 /**
  * Recency comparator: most-recently-updated first, with a `seq` tiebreak so
  * equal-`updated` records sort deterministically. Mirrors the B1 index ordering.
@@ -2650,20 +2935,22 @@ export declare class RecencyRetriever implements IMemoryRetriever {
 /**
  * The four dedup verdicts a {@link IEntityResolver} (or fgv's exact-match layer)
  * returns for a candidate. See the design note §3 for the verdict → write
- * disposition mapping.
+ * disposition mapping. Each target-bearing arm carries a scope-qualified
+ * {@link IEdgeTarget} (not a bare {@link MemoryId}) so the verdict resolves to a
+ * single record even when a filename stem is reused across scopes.
  * @public
  */
 export declare type ResolutionVerdict = {
     readonly verdict: 'new';
 } | {
     readonly verdict: 'duplicate-of';
-    readonly target: MemoryId;
+    readonly target: IEdgeTarget;
 } | {
     readonly verdict: 'supersede';
-    readonly target: MemoryId;
+    readonly target: IEdgeTarget;
 } | {
     readonly verdict: 'merge-into';
-    readonly target: MemoryId;
+    readonly target: IEdgeTarget;
 };
 
 /**