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

package/src/packlets/tools/memoryTools.ts

@@ -6,7 +6,7 @@
 import { Result, captureResult, fail, succeed } from '@fgv/ts-utils';
 import { JsonSchema } from '@fgv/ts-json-base';
 import { AiAssist } from '@fgv/ts-extras';
-import { Convert, EntityId, IIdentityCodec, IMemoryRecord, Kind, MemoryId, Tag } from '../types';
+import { Convert, EntityId, IEdgeTarget, IIdentityCodec, IMemoryRecord, Kind, MemoryId, Tag } from '../types';
 import { IBodyConverterRegistry, envelopeConverter } from '../converters';
 import { IMemoryStore } from '../store';
 import { IMemoryQuery, IMemoryRetriever } from '../retrieve';
@@ -135,8 +135,33 @@ export 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;
 }
 
+/**
+ * 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 type MemoryDetailTier = 'gist' | 'full';
+
 /** The resolved factory context threaded into each tool's `execute`. */
 interface IToolContext {
   readonly store: IMemoryStore;
@@ -146,6 +171,7 @@ interface IToolContext {
   readonly codecs?: ReadonlyMap<Kind, IIdentityCodec>;
   readonly defaultCodec?: IIdentityCodec;
   readonly handleFor?: (record: IMemoryRecord<unknown>) => string;
+  readonly projectItem?: (record: IMemoryRecord<unknown>, detail: MemoryDetailTier) => IMemoryToolResultItem;
 }
 
 // ---------------------------------------------------------------------------
@@ -155,11 +181,27 @@ interface IToolContext {
 // gate is enforced structurally and asserted in the tests.
 // ---------------------------------------------------------------------------
 
+/**
+ * The scope-qualified target of a link edge authored by the agent on a write.
+ * `scope` is optional: when omitted it defaults to the writing record's OWN
+ * resolved scope (the common same-conversation case); supply it explicitly to
+ * point an edge at a record in a different scope.
+ */
+// eslint-disable-next-line @rushstack/typedef-var
+const linkTargetSchema = JsonSchema.object({
+  id: JsonSchema.string({ description: 'The MemoryId of the record this edge points at.' }),
+  scope: JsonSchema.optional(
+    JsonSchema.string({
+      description: "The target record's scope. Defaults to the writing record's own scope when omitted."
+    })
+  )
+});
+
 /** A single attributed link edge as authored by the agent on a write. */
 // eslint-disable-next-line @rushstack/typedef-var
 const linkEdgeSchema = JsonSchema.object({
   type: JsonSchema.string({ description: 'The relation type of the link.' }),
-  target: JsonSchema.string({ description: 'The MemoryId this edge points at.' }),
+  target: linkTargetSchema,
   confidence: JsonSchema.optional(JsonSchema.number({ description: 'Optional confidence in [0, 1].' }))
 });
 
@@ -179,7 +221,10 @@ type WriteArgs = JsonSchema.Static<typeof writeSchema>;
 // eslint-disable-next-line @rushstack/typedef-var
 const readSchema = JsonSchema.object({
   kind: JsonSchema.string({ description: 'The record kind.' }),
-  entityId: JsonSchema.string({ description: 'The domain entity id to read.' })
+  entityId: JsonSchema.string({ description: 'The domain entity id to read.' }),
+  detail: JsonSchema.optional(
+    JsonSchema.enumOf(['gist', 'full'] as const, { description: "'gist' | 'full' (default)." })
+  )
 });
 
 // eslint-disable-next-line @rushstack/typedef-var
@@ -195,16 +240,41 @@ const searchSchema = JsonSchema.object({
   semantic: JsonSchema.optional(
     JsonSchema.string({ description: 'Semantic query text (requires a semantic-capable retriever).' })
   ),
-  limit: JsonSchema.optional(JsonSchema.integer({ description: 'Maximum number of results to return.' }))
+  limit: JsonSchema.optional(JsonSchema.integer({ description: 'Maximum number of results to return.' })),
+  offset: JsonSchema.optional(
+    JsonSchema.integer({ description: 'Number of results to skip after ordering, before limit. Default 0.' })
+  ),
+  detail: JsonSchema.optional(
+    JsonSchema.enumOf(['gist', 'full'] as const, { description: "'gist' (default) | 'full'." })
+  )
+});
+
+/**
+ * The scope-qualified seed a `memory_context` traversal starts from. Nested
+ * `{ id, scope }` shape like a link target, but — unlike a write edge — there is
+ * no writing record to default the scope from, so `scope` is REQUIRED to
+ * disambiguate the seed across scopes (a bare stem like `turn-3` is otherwise
+ * ambiguous). It is schema-required (not just runtime-required) so the wire
+ * schema an LLM reads never advertises an optionality the tool does not honor.
+ */
+// eslint-disable-next-line @rushstack/typedef-var
+const contextSeedSchema = JsonSchema.object({
+  id: JsonSchema.string({ description: 'The MemoryId of the seed record to traverse links from.' }),
+  scope: JsonSchema.string({
+    description: 'The scope of the seed record (required — a bare seed id is ambiguous across scopes).'
+  })
 });
 
 // eslint-disable-next-line @rushstack/typedef-var
 const contextSchema = JsonSchema.object({
-  from: JsonSchema.string({ description: 'The seed MemoryId to traverse links from.' }),
+  from: contextSeedSchema,
   kind: JsonSchema.optional(JsonSchema.string({ description: 'Restrict reached records to this kind.' })),
   tag: JsonSchema.optional(JsonSchema.string({ description: 'Restrict reached records carrying this tag.' })),
   hops: JsonSchema.optional(JsonSchema.integer({ description: 'BFS hop count (default 1).' })),
-  limit: JsonSchema.optional(JsonSchema.integer({ description: 'Maximum number of results to return.' }))
+  limit: JsonSchema.optional(JsonSchema.integer({ description: 'Maximum number of results to return.' })),
+  detail: JsonSchema.optional(
+    JsonSchema.enumOf(['gist', 'full'] as const, { description: "'gist' (default) | 'full'." })
+  )
 });
 
 // ---------------------------------------------------------------------------
@@ -254,8 +324,17 @@ function resolveOptionalKind(ctx: IToolContext, kindStr?: string): Result<Kind |
   return assertKindEnabled(ctx, kindStr);
 }
 
-/** Project a record into an agent-visible result item, applying the host handle hook when present. */
-function projectItem(ctx: IToolContext, record: IMemoryRecord<unknown>): IMemoryToolResultItem {
+/**
+ * Resolve the requested detail tier from the optional tool `detail` string.
+ * `'full'` is the only opt-in value; every other input (absent, or an
+ * unrecognized string) resolves safely to the bounded default `'gist'`.
+ */
+function resolveDetail(detail?: string): MemoryDetailTier {
+  return detail === 'full' ? 'full' : 'gist';
+}
+
+/** The built-in default projection: full body plus the guarded host handle. Ignores the detail tier. */
+function defaultProjectItem(ctx: IToolContext, record: IMemoryRecord<unknown>): IMemoryToolResultItem {
   // `handleFor` is a host callback; guard it so a throw degrades to the raw id rather than
   // escaping the Result chain (and crashing the whole search/context call).
   const handle =
@@ -271,6 +350,27 @@ function projectItem(ctx: IToolContext, record: IMemoryRecord<unknown>): IMemory
   };
 }
 
+/**
+ * Project a record into an agent-visible result item at the requested detail
+ * tier. When a host {@link ICreateMemoryToolsParams.projectItem | projectItem}
+ * is supplied it owns the projection; otherwise the built-in
+ * {@link defaultProjectItem} (full body) is used. The host callback is guarded
+ * like `handleFor` — a throw degrades to the default full-body projection for
+ * that item rather than failing the whole search/context call.
+ */
+function projectItem(
+  ctx: IToolContext,
+  record: IMemoryRecord<unknown>,
+  detail: MemoryDetailTier
+): IMemoryToolResultItem {
+  if (ctx.projectItem === undefined) {
+    return defaultProjectItem(ctx, record);
+  }
+  // Guard the host projector like `handleFor`: a throw degrades to the built-in
+  // full-body projection (itself throw-safe) rather than escaping the chain.
+  return captureResult(() => ctx.projectItem!(record, detail)).orDefault(defaultProjectItem(ctx, record));
+}
+
 /** Resolve the identity codec used by `memory_write` to derive the storage id. */
 function codecForWrite(ctx: IToolContext, kind: Kind): Result<IIdentityCodec> {
   const codec: IIdentityCodec | undefined = ctx.codecs?.get(kind) ?? ctx.defaultCodec;
@@ -285,13 +385,16 @@ function buildWriteRecord(
   typed: WriteArgs,
   kind: Kind,
   entityId: EntityId,
-  idStem: string
+  idStem: string,
+  sourceScope: string
 ): Result<IMemoryRecord<unknown>> {
   // Plain shapes handed to `envelopeConverter`, which validates each field
-  // (type → LinkType, target → MemoryId) and produces the branded IEdge[].
+  // (type → LinkType, target → { scope, id }) and produces the branded IEdge[].
+  // An edge target with no explicit `scope` defaults to the writing record's own
+  // resolved scope — the same-conversation case authors just an id.
   const links: ReadonlyArray<Record<string, unknown>> = (typed.links ?? []).map((link) => ({
     type: link.type,
-    target: link.target,
+    target: { scope: link.target.scope ?? sourceScope, id: link.target.id },
     ...(link.confidence !== undefined ? { confidence: link.confidence } : {})
   }));
   return envelopeConverter
@@ -323,7 +426,7 @@ function prepareWrite(
           if (addr.isVersioned) {
             return fail(`memory_write: versioned/temporal kind '${kind}' is not supported`);
           }
-          return buildWriteRecord(typed, kind, entityId, addr.idStem).onSuccess((record) =>
+          return buildWriteRecord(typed, kind, entityId, addr.idStem, addr.scope).onSuccess((record) =>
             succeed({ kind, entityId, record })
           );
         })
@@ -418,14 +521,19 @@ function buildReadTool(ctx: IToolContext): AiAssist.IAiClientTool {
         .withErrorFormat((msg) => `memory_read: invalid arguments: ${msg}`)
         .onSuccess((typed) =>
           assertKindEnabled(ctx, typed.kind).onSuccess((kind) =>
-            Convert.entityId.convert(typed.entityId).onSuccess((entityId) => succeed({ kind, entityId }))
+            Convert.entityId.convert(typed.entityId).onSuccess((entityId) => {
+              // `memory_read` is the explicit drill-in path, so its detail default is
+              // INVERTED vs search/context: `'full'` unless the caller opts down to `'gist'`.
+              const detail: MemoryDetailTier = typed.detail === 'gist' ? 'gist' : 'full';
+              return succeed({ kind, entityId, detail });
+            })
           )
         )
-        .thenOnSuccess(async ({ kind, entityId }) =>
+        .thenOnSuccess(async ({ kind, entityId, detail }) =>
           (await ctx.store.get(kind, entityId)).onSuccess((record) =>
             record === undefined
               ? succeed({ found: false })
-              : succeed({ found: true, item: projectItem(ctx, record) })
+              : succeed({ found: true, item: projectItem(ctx, record, detail) })
           )
         )
   };
@@ -450,14 +558,16 @@ function buildSearchTool(ctx: IToolContext): AiAssist.IAiClientTool {
           )
         )
         .thenOnSuccess(async ({ typed, kind, tag }) => {
+          const detail: MemoryDetailTier = resolveDetail(typed.detail);
           const query: IMemoryQuery = {
             ...(kind !== undefined ? { kind } : {}),
             ...(tag !== undefined ? { tag } : {}),
             ...(typed.semantic !== undefined ? { semantic: typed.semantic } : {}),
-            ...(typed.limit !== undefined ? { limit: typed.limit } : {})
+            ...(typed.limit !== undefined ? { limit: typed.limit } : {}),
+            ...(typed.offset !== undefined ? { offset: typed.offset } : {})
           };
           return (await ctx.retriever.retrieve(query)).onSuccess((records) =>
-            succeed({ count: records.length, results: records.map((r) => projectItem(ctx, r)) })
+            succeed({ count: records.length, results: records.map((r) => projectItem(ctx, r, detail)) })
           );
         })
   };
@@ -478,15 +588,14 @@ function buildContextTool(ctx: IToolContext): AiAssist.IAiClientTool {
         .convert(args)
         .withErrorFormat((msg) => `memory_context: invalid arguments: ${msg}`)
         .onSuccess((typed) =>
-          Convert.memoryId
-            .convert(typed.from)
-            .onSuccess((from) =>
-              resolveOptionalKind(ctx, typed.kind).onSuccess((kind) =>
-                resolveOptionalTag(typed.tag).onSuccess((tag) => succeed({ typed, from, kind, tag }))
-              )
+          resolveContextSeed(typed.from).onSuccess((from) =>
+            resolveOptionalKind(ctx, typed.kind).onSuccess((kind) =>
+              resolveOptionalTag(typed.tag).onSuccess((tag) => succeed({ typed, from, kind, tag }))
             )
+          )
         )
         .thenOnSuccess(async ({ typed, from, kind, tag }) => {
+          const detail: MemoryDetailTier = resolveDetail(typed.detail);
           const query: IMemoryQuery = {
             linkedFrom: from,
             ...(kind !== undefined ? { kind } : {}),
@@ -495,7 +604,11 @@ function buildContextTool(ctx: IToolContext): AiAssist.IAiClientTool {
             ...(typed.limit !== undefined ? { limit: typed.limit } : {})
           };
           return (await ctx.retriever.retrieve(query)).onSuccess((records) =>
-            succeed({ seed: from, count: records.length, results: records.map((r) => projectItem(ctx, r)) })
+            succeed({
+              seed: from,
+              count: records.length,
+              results: records.map((r) => projectItem(ctx, r, detail))
+            })
           );
         })
   };
@@ -527,6 +640,19 @@ function buildDeleteTool(ctx: IToolContext): AiAssist.IAiClientTool {
   };
 }
 
+/**
+ * Resolve a `memory_context` seed argument into a scope-qualified
+ * {@link IEdgeTarget}. Both `id` and `scope` are present here — the tool's
+ * `parametersSchema` ({@link contextSeedSchema}) makes `scope` schema-required —
+ * so this only brands the two fields; a malformed value fails via the branded
+ * converters (e.g. a path-unsafe seed id).
+ */
+function resolveContextSeed(from: { readonly id: string; readonly scope: string }): Result<IEdgeTarget> {
+  return Convert.memoryId
+    .convert(from.id)
+    .onSuccess((id) => Convert.scopeKey.convert(from.scope).onSuccess((scope) => succeed({ scope, id })));
+}
+
 /** Validate an optional `tag` string (`undefined` passes through). */
 function resolveOptionalTag(tagStr?: string): Result<Tag | undefined> {
   if (tagStr === undefined) {
@@ -572,7 +698,8 @@ export function createMemoryTools(params: ICreateMemoryToolsParams): ReadonlyArr
     kinds: params.kinds,
     codecs: params.codecs,
     defaultCodec: params.defaultCodec,
-    handleFor: params.handleFor
+    handleFor: params.handleFor,
+    projectItem: params.projectItem
   };
   const selected: ReadonlySet<MemoryToolName> = new Set<MemoryToolName>(params.tools ?? DEFAULT_MEMORY_TOOLS);
   return TOOL_BUILDERS.filter((builder) => selected.has(builder.name)).map((builder) => builder.build(ctx));

package/src/packlets/types/envelope.ts

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: MIT
  */
 
-import { EntityId, Kind, LinkType, MemoryId, Tag } from './ids';
+import { EntityId, Kind, LinkType, MemoryId, MemoryScopeKey, Tag } from './ids';
 
 /**
  * Origin of a provenance attribution. Open vocabulary: the three named
@@ -29,24 +29,61 @@ export 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;
 }
 
+/**
+ * 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 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;
+}
+
+/**
+ * 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 function edgeTargetKey(target: IEdgeTarget): string {
+  return `${target.scope}\0${target.id}`;
+}
+
 /**
  * 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 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. */
@@ -108,6 +145,15 @@ export 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;
 
@@ -136,3 +182,15 @@ export interface IMemoryRecord<TBody = unknown> {
   /** The per-kind, Converter-validated body. */
   readonly body: TBody;
 }
+
+/**
+ * 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 type RankProjector = (record: IMemoryRecord<unknown>) => number;

package/src/packlets/vector/inMemoryCosineIndex.ts

@@ -4,8 +4,20 @@
  */
 
 import { Result, fail, succeed } from '@fgv/ts-utils';
-import { IMemoryRecord, MemoryId } from '../types';
-import { IMemoryRecordSource, IVectorIndex, IVectorQueryHit, MemoryEmbedder } from './vectorIndex';
+import { IEdgeTarget, edgeTargetKey } from '../types';
+import {
+  IMemoryRecordSource,
+  IScopedMemoryRecord,
+  IVectorIndex,
+  IVectorQueryHit,
+  MemoryEmbedder
+} from './vectorIndex';
+
+/** One stored embedding: the scope-qualified address plus its vector. */
+interface IStoredVector {
+  readonly target: IEdgeTarget;
+  readonly vector: Float32Array;
+}
 
 /**
  * The brute-force, in-memory cosine {@link IVectorIndex}. Stores one
@@ -31,12 +43,17 @@ import { IMemoryRecordSource, IVectorIndex, IVectorQueryHit, MemoryEmbedder } fr
  * @public
  */
 export class InMemoryCosineIndex implements IVectorIndex {
-  private readonly _vectors: Map<MemoryId, Float32Array>;
+  /**
+   * 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: Map<string, IStoredVector>;
   /** The dimension of every stored vector; `undefined` until the first `add`. */
   private _dimension: number | undefined;
 
   private constructor() {
-    this._vectors = new Map<MemoryId, Float32Array>();
+    this._vectors = new Map<string, IStoredVector>();
     this._dimension = undefined;
   }
 
@@ -51,30 +68,32 @@ export class InMemoryCosineIndex implements IVectorIndex {
   }
 
   /** {@inheritDoc IVectorIndex.add} */
-  public add(id: MemoryId, vector: Float32Array): Promise<Result<string>> {
+  public add(target: IEdgeTarget, vector: Float32Array): Promise<Result<string>> {
+    const key: string = edgeTargetKey(target);
     if (vector.length === 0) {
-      return Promise.resolve(fail(`vector index: cannot add '${id}': empty vector`));
+      return Promise.resolve(fail(`vector index: cannot add '${key}': empty vector`));
     }
     if (this._dimension === undefined) {
       this._dimension = vector.length;
     } else if (vector.length !== this._dimension) {
       return Promise.resolve(
         fail(
-          `vector index: cannot add '${id}': dimension ${vector.length} does not match index dimension ${this._dimension}`
+          `vector index: cannot add '${key}': dimension ${vector.length} does not match index dimension ${this._dimension}`
         )
       );
     }
     // Defensive copy: the caller may reuse or mutate the buffer after `add`, and
     // the index must keep serving the embedding it was given.
-    this._vectors.set(id, Float32Array.from(vector));
-    // The in-memory index keys entries by id, so the id IS the entry reference.
-    return Promise.resolve(succeed(id as string));
+    this._vectors.set(key, { target, vector: Float32Array.from(vector) });
+    // The in-memory index keys entries by the canonical scoped-target string, so
+    // that key IS the entry reference.
+    return Promise.resolve(succeed(key));
   }
 
   /** {@inheritDoc IVectorIndex.remove} */
-  public remove(id: MemoryId): Promise<Result<MemoryId>> {
-    this._vectors.delete(id);
-    return Promise.resolve(succeed(id));
+  public remove(target: IEdgeTarget): Promise<Result<IEdgeTarget>> {
+    this._vectors.delete(edgeTargetKey(target));
+    return Promise.resolve(succeed(target));
   }
 
   /** {@inheritDoc IVectorIndex.query} */
@@ -91,8 +110,11 @@ export class InMemoryCosineIndex implements IVectorIndex {
     }
     const queryMagnitude: number = InMemoryCosineIndex._magnitude(vector);
     const hits: IVectorQueryHit[] = [];
-    for (const [id, stored] of this._vectors) {
-      hits.push({ id, score: InMemoryCosineIndex._cosine(vector, queryMagnitude, stored) });
+    for (const stored of this._vectors.values()) {
+      hits.push({
+        target: stored.target,
+        score: InMemoryCosineIndex._cosine(vector, queryMagnitude, stored.vector)
+      });
     }
     // Descending by score; a `seq`-free tiebreak is unnecessary here because the
     // caller (SemanticRetriever) re-resolves hits against the record index.
@@ -110,8 +132,7 @@ export 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.
    */
   public async rebuild(source: IMemoryRecordSource, embed: MemoryEmbedder): Promise<Result<number>> {
@@ -119,17 +140,19 @@ export class InMemoryCosineIndex implements IVectorIndex {
     // even when the listing itself fails (no stale vectors survive a failed
     // rebuild).
     this._reset();
-    const listed: Result<ReadonlyArray<IMemoryRecord<unknown>>> = await source.list();
+    const listed: Result<ReadonlyArray<IScopedMemoryRecord>> = await source.list();
     if (listed.isFailure()) {
       return fail(`vector index rebuild: failed to list records: ${listed.message}`);
     }
-    for (const record of listed.value) {
-      const embedded: Result<Float32Array> = await embed(record);
+    for (const scoped of listed.value) {
+      const embedded: Result<Float32Array> = await embed(scoped.record);
       if (embedded.isFailure()) {
         this._reset();
-        return fail(`vector index rebuild: embedding '${record.envelope.id}' failed: ${embedded.message}`);
+        return fail(
+          `vector index rebuild: embedding '${edgeTargetKey(scoped.target)}' failed: ${embedded.message}`
+        );
       }
-      const added: Result<string> = await this.add(record.envelope.id, embedded.value);
+      const added: Result<string> = await this.add(scoped.target, embedded.value);
       if (added.isFailure()) {
         this._reset();
         return fail(`vector index rebuild: ${added.message}`);

package/src/packlets/vector/vectorIndex.ts

@@ -4,17 +4,25 @@
  */
 
 import { Result } from '@fgv/ts-utils';
-import { IMemoryRecord, MemoryId } from '../types';
+import { IEdgeTarget, IMemoryRecord } from '../types';
 
 /**
- * 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 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;
 }
@@ -36,17 +44,20 @@ export interface IVectorQueryHit {
  */
 export 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.
@@ -63,16 +74,32 @@ export interface IVectorIndex {
  */
 export type MemoryEmbedder = (record: IMemoryRecord<unknown>) => Promise<Result<Float32Array>>;
 
+/**
+ * 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 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 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 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>>>;
 }