@herbertgao/pi-extensions 2026.8.11 → 2026.8.13

package/node_modules/@luxusai/pi-hindsight/extensions/operations/memory-diagnostics-operations.ts

@@ -0,0 +1,105 @@
+import { checkHindsight } from "../client/client.js";
+import { formatDebugReport } from "../utils/diagnostics.js";
+import { resolveQueuePath, summarizeRetainQueue } from "../queue/queue.js";
+import {
+  importManifestSummary,
+  readImportManifestSafe,
+  resolveImportManifestPath,
+} from "../imports/import-plan.js";
+import { buildSyncStatus, DEFAULT_GIT_SEED_LIMIT, seedGitLog } from "../lifecycle/git-seed.js";
+import type { MemoryOperationsDeps } from "./memory-operation-types.js";
+import {
+  buildScopeMigratePlan,
+  writeScopeMigrateReceipt,
+  type ScopeMigratePlan,
+} from "./scope-migrate.js";
+
+export function createDiagnosticsOperations(deps: MemoryOperationsDeps) {
+  return {
+    async doctor(cwd: string, sessionFile?: string): Promise<string> {
+      const config = deps.getConfig();
+      const projectBankId = deps.getProjectBankId();
+      const manifestPath = resolveImportManifestPath(cwd, config.import.manifestPath);
+      const [health, queueSummary, manifestResult, sync] = await Promise.all([
+        checkHindsight(deps.getClient(), projectBankId),
+        summarizeRetainQueue(resolveQueuePath(cwd, config.retain.queuePath)),
+        readImportManifestSafe(manifestPath),
+        buildSyncStatus({
+          cwd,
+          config,
+          client: deps.getClient(),
+          bankId: projectBankId,
+        }),
+      ]);
+      const imports = importManifestSummary(manifestResult.manifest);
+      const scopeMigrate = buildScopeMigratePlan({ cwd, config, projectBankId });
+      return formatDebugReport({
+        cwd,
+        ...(sessionFile ? { sessionFile } : {}),
+        projectBankId,
+        config,
+        queueLength: queueSummary.active.valid,
+        queuePath: queueSummary.active.path,
+        queueMalformedLines: queueSummary.active.malformed,
+        queueReadError: queueSummary.active.error,
+        deadLetterPath: queueSummary.deadLetter.path,
+        deadLetterLength: queueSummary.deadLetter.valid,
+        deadLetterMalformedLines: queueSummary.deadLetter.malformed,
+        deadLetterReadError: queueSummary.deadLetter.error,
+        importManifestPath: manifestPath,
+        importManifestError: manifestResult.error,
+        importManifestAction: manifestResult.action,
+        importCount: imports.count,
+        ...(imports.latest ? { latestImport: imports.latest } : {}),
+        health,
+        scopeMigrate,
+        sync,
+      });
+    },
+
+    /** Memory readiness: queue depth, git seed receipt, knowledge-page capability. */
+    async syncStatus(cwd: string) {
+      return buildSyncStatus({
+        cwd,
+        config: deps.getConfig(),
+        client: deps.getClient(),
+        bankId: deps.getProjectBankId(),
+      });
+    },
+
+    /**
+     * Opt-in cold-repo gitlog seed (commit messages only). dryRun defaults true.
+     * Does not auto-run on session start — conversation retain remains the product core.
+     */
+    async seedGitLog(args: { cwd: string; limit?: number; dryRun?: boolean; flush?: boolean }) {
+      return seedGitLog({
+        cwd: args.cwd,
+        bankId: deps.getProjectBankId(),
+        config: deps.getConfig(),
+        client: deps.getClient(),
+        limit: args.limit ?? DEFAULT_GIT_SEED_LIMIT,
+        dryRun: args.dryRun ?? true,
+        ...(args.flush !== undefined ? { flush: args.flush } : {}),
+      });
+    },
+
+    /**
+     * Dry-run only: plan dual-tag / legacy repo-tag migration guidance and write a local receipt.
+     * Never rewrites Hindsight tags or documents.
+     */
+    async scopeMigrateDryRun(
+      cwd: string,
+      options: { bankTags?: string[]; writeReceipt?: boolean } = {},
+    ): Promise<ScopeMigratePlan | import("./scope-migrate.js").ScopeMigrateReceipt> {
+      const config = deps.getConfig();
+      const plan = buildScopeMigratePlan({
+        cwd,
+        config,
+        projectBankId: deps.getProjectBankId(),
+        ...(options.bankTags ? { bankTags: options.bankTags } : {}),
+      });
+      if (options.writeReceipt === false) return plan;
+      return writeScopeMigrateReceipt(cwd, plan);
+    },
+  };
+}

package/node_modules/@luxusai/pi-hindsight/extensions/operations/memory-identity.ts

@@ -0,0 +1,68 @@
+import type { ResolvedConfig } from "../types.js";
+import {
+  baseTags,
+  deriveProjectBankId,
+  recallScopeTags,
+  resolveProjectIdentity,
+  type ProjectIdBasis,
+} from "../banks/banking.js";
+import { importDocumentId, liveDocumentId, stableSessionId } from "../utils/session.js";
+
+export interface MemoryIdentity {
+  cwd: string;
+  sessionFile?: string;
+  /** Stable project id (pin / remote / basename). */
+  projectId: string;
+  projectIdBasis: ProjectIdBasis;
+  projectIdSource: string;
+  /** Legacy path-hash key; still dual-tagged during migration. */
+  repoKey: string;
+  sessionId: string;
+  projectBankId: string;
+  liveDocumentId: string;
+  baseTags: string[];
+  projectRecallTags: string[];
+  globalRecallTags: string[];
+}
+
+export function uniqueTags(tags: string[]): string[] {
+  return [...new Set(tags.filter(Boolean))];
+}
+
+export function mergeBaseAndExtraTags(base: string[], extra: string[] | undefined): string[] {
+  return uniqueTags([...base, ...(extra ?? [])]);
+}
+
+export function createMemoryIdentity(
+  cwd: string,
+  config: ResolvedConfig,
+  sessionFile?: string,
+): MemoryIdentity {
+  const sessionId = stableSessionId(sessionFile, cwd);
+  const project = resolveProjectIdentity(cwd, config);
+  return {
+    cwd,
+    ...(sessionFile ? { sessionFile } : {}),
+    projectId: project.projectId,
+    projectIdBasis: project.basis,
+    projectIdSource: project.source,
+    repoKey: project.legacyRepoKey,
+    sessionId,
+    projectBankId: deriveProjectBankId(cwd, config),
+    liveDocumentId: liveDocumentId(sessionFile, cwd),
+    baseTags: baseTags(cwd, sessionId, config),
+    projectRecallTags: recallScopeTags(cwd, config),
+    globalRecallTags: ["source:pi"],
+  };
+}
+
+export function explicitRetainTags(
+  cwd: string,
+  sessionFile: string | undefined,
+  extraTags: string[] | undefined,
+  config?: ResolvedConfig,
+): string[] {
+  return mergeBaseAndExtraTags(baseTags(cwd, stableSessionId(sessionFile, cwd), config), extraTags);
+}
+
+export { importDocumentId, liveDocumentId, stableSessionId };

package/node_modules/@luxusai/pi-hindsight/extensions/operations/memory-operation-service.ts

@@ -0,0 +1,71 @@
+import type { MemoryOperationsDeps } from "./memory-operation-types.js";
+import {
+  importMemoryChatTranscript,
+  importMemoryProjectSessions,
+  importMemorySession,
+} from "../imports/import-sessions.js";
+import { createBankTemplateOperations } from "./memory-bank-template-operations.js";
+import { createConfigOperations } from "./memory-config-operations.js";
+import { createControlOperations } from "./memory-control-operations.js";
+import { createDiagnosticsOperations } from "./memory-diagnostics-operations.js";
+import { createQueueOperations } from "../queue/queue-operations.js";
+import { createRecallOperations } from "./memory-recall-operations.js";
+import { createRetainOperations } from "./memory-retain-operations.js";
+import { createSessionOperations } from "./memory-session-operations.js";
+import type { ResolvedConfig } from "../types.js";
+import type { ImportProgressReporter } from "../imports/import-sessions.js";
+
+export type { ConfigureMemoryArgs, MemoryOperationsDeps } from "./memory-operation-types.js";
+
+function createImportOperations(deps: MemoryOperationsDeps) {
+  return {
+    async importSession(args: {
+      sessionFile: string;
+      cwd?: string;
+      bank?: string;
+      dryRun?: boolean;
+      includeBranches?: ResolvedConfig["import"]["includeBranches"];
+      onProgress?: ImportProgressReporter;
+    }) {
+      return importMemorySession(args, deps);
+    },
+
+    async importChatTranscript(args: {
+      sourceFile: string;
+      cwd: string;
+      bank?: string;
+      dryRun?: boolean;
+      onProgress?: ImportProgressReporter;
+    }) {
+      return importMemoryChatTranscript(args, deps);
+    },
+
+    async importProjectSessions(args: {
+      cwd: string;
+      currentSessionFile?: string;
+      searchDir?: string;
+      bank?: string;
+      dryRun?: boolean;
+      includeBranches?: ResolvedConfig["import"]["includeBranches"];
+      onProgress?: ImportProgressReporter;
+    }) {
+      return importMemoryProjectSessions(args, deps);
+    },
+  };
+}
+
+export function createMemoryOperations(deps: MemoryOperationsDeps) {
+  return {
+    ...createRecallOperations(deps),
+    ...createRetainOperations(deps),
+    ...createConfigOperations(deps),
+    ...createImportOperations(deps),
+    ...createQueueOperations(deps),
+    ...createSessionOperations(),
+    ...createDiagnosticsOperations(deps),
+    ...createBankTemplateOperations(deps),
+    ...createControlOperations(deps),
+  };
+}
+
+export type MemoryOperations = ReturnType<typeof createMemoryOperations>;

package/node_modules/@luxusai/pi-hindsight/extensions/operations/memory-operation-types.ts

@@ -0,0 +1,13 @@
+import type { HindsightLikeClient, ResolvedConfig } from "../types.js";
+import type { ProjectConfigPatchInput } from "../config/config-writer.js";
+import type { InitHealth } from "../lifecycle/memory-lifecycle.js";
+
+export interface MemoryOperationsDeps {
+  getClient(): HindsightLikeClient;
+  getConfig(): ResolvedConfig;
+  getProjectBankId(): string;
+  getInitHealth?(): InitHealth | undefined;
+  reloadConfig?(cwd: string): void;
+}
+
+export type ConfigureMemoryArgs = ProjectConfigPatchInput;

package/node_modules/@luxusai/pi-hindsight/extensions/operations/memory-recall-operations.ts

@@ -0,0 +1,162 @@
+import type { MemoryOperationsDeps } from "./memory-operation-types.js";
+import { composeScopedTagFilter, scopeTagsForBank } from "./memory-scope.js";
+import { resolveOperationBank } from "../banks/bank-selection.js";
+import { readLastRecallSnapshot, resolveLastRecallPath } from "../lifecycle/recall-visibility.js";
+import {
+  pruneTranscriptRecallBlocks,
+  scanTranscriptForRecallBlocks,
+} from "../lifecycle/recall-cleanup.js";
+import {
+  getEffectiveSessionMemoryMode,
+  readSessionMemoryMeta,
+} from "../utils/session-memory-meta.js";
+import type { HindsightTagGroup, TagsMatch } from "../types.js";
+import type { MinScores } from "@vectorize-io/hindsight-client";
+
+interface ExplicitRecallFilters {
+  budget?: import("../types.js").Budget;
+  maxTokens?: number;
+  queryTimestamp?: string;
+  types?: string[];
+  preferObservations?: boolean;
+  minScores?: MinScores;
+  trace?: boolean;
+  includeEntities?: boolean;
+  maxEntityTokens?: number;
+  includeChunks?: boolean;
+  maxChunkTokens?: number;
+  includeSourceFacts?: boolean;
+  maxSourceFactsTokens?: number;
+  tags?: string[];
+  tagsMatch?: TagsMatch;
+  tagGroups?: HindsightTagGroup[];
+  /** Override config.scope.includeSharedObservations for this call when set. */
+  includeSharedObservations?: boolean;
+  signal?: AbortSignal;
+}
+
+interface ExplicitReflectFilters extends Omit<ExplicitRecallFilters, "queryTimestamp" | "types"> {
+  includeFacts?: boolean;
+  includeToolCalls?: boolean;
+  includeToolCallOutput?: boolean;
+  factTypes?: Array<"world" | "experience" | "observation">;
+  excludeMentalModels?: boolean;
+  excludeMentalModelIds?: string[];
+}
+
+export function createRecallOperations(deps: MemoryOperationsDeps) {
+  return {
+    async recall(
+      cwd: string,
+      query: string,
+      bank?: string,
+      sessionFile?: string,
+      filters: ExplicitRecallFilters = {},
+    ) {
+      const meta = await readSessionMemoryMeta(cwd, sessionFile);
+      if (!getEffectiveSessionMemoryMode(meta).recall)
+        throw new Error("Hindsight recall is disabled for this session");
+      const config = deps.getConfig();
+      const bankId = resolveOperationBank({
+        requestedBank: bank,
+        config,
+        projectBankId: deps.getProjectBankId(),
+      });
+      const scopeTags = scopeTagsForBank(cwd, config, bankId);
+      const includeShared =
+        filters.includeSharedObservations ?? config.scope.includeSharedObservations;
+      const result = await deps.getClient().recall(bankId, query, {
+        budget: filters.budget ?? config.recall.budget,
+        maxTokens: filters.maxTokens ?? config.recall.maxTokens,
+        ...(filters.queryTimestamp || config.recall.queryTimestamp
+          ? { queryTimestamp: filters.queryTimestamp ?? config.recall.queryTimestamp }
+          : {}),
+        ...(filters.types ? { types: filters.types } : {}),
+        preferObservations: config.recall.preferObservations,
+        ...(filters.preferObservations !== undefined
+          ? { preferObservations: filters.preferObservations }
+          : {}),
+        ...(filters.minScores !== undefined ? { minScores: filters.minScores } : {}),
+        ...(filters.trace !== undefined ? { trace: filters.trace } : {}),
+        ...(filters.includeEntities !== undefined
+          ? { includeEntities: filters.includeEntities }
+          : {}),
+        ...(filters.maxEntityTokens !== undefined
+          ? { maxEntityTokens: filters.maxEntityTokens }
+          : {}),
+        ...(filters.includeChunks !== undefined ? { includeChunks: filters.includeChunks } : {}),
+        ...(filters.maxChunkTokens !== undefined ? { maxChunkTokens: filters.maxChunkTokens } : {}),
+        ...(filters.includeSourceFacts !== undefined
+          ? { includeSourceFacts: filters.includeSourceFacts }
+          : {}),
+        ...(filters.maxSourceFactsTokens !== undefined
+          ? { maxSourceFactsTokens: filters.maxSourceFactsTokens }
+          : {}),
+        ...composeScopedTagFilter(scopeTags, {
+          ...filters,
+          includeSharedObservations: includeShared,
+        }),
+        ...(filters.signal ? { signal: filters.signal } : {}),
+      });
+      return { bankId, result };
+    },
+
+    async reflect(
+      cwd: string,
+      query: string,
+      context?: string,
+      bank?: string,
+      responseSchema?: Record<string, unknown>,
+      filters: ExplicitReflectFilters = {},
+    ) {
+      const config = deps.getConfig();
+      const bankId = resolveOperationBank({
+        requestedBank: bank,
+        config,
+        projectBankId: deps.getProjectBankId(),
+      });
+      const scopeTags = scopeTagsForBank(cwd, config, bankId);
+      const includeShared =
+        filters.includeSharedObservations ?? config.scope.includeSharedObservations;
+      const result = await deps.getClient().reflect(bankId, query, {
+        ...(context ? { context } : {}),
+        budget: filters.budget ?? config.recall.budget,
+        ...(filters.maxTokens !== undefined ? { maxTokens: filters.maxTokens } : {}),
+        ...(responseSchema ? { responseSchema } : {}),
+        ...(filters.includeFacts !== undefined ? { includeFacts: filters.includeFacts } : {}),
+        ...(filters.includeToolCalls !== undefined
+          ? { includeToolCalls: filters.includeToolCalls }
+          : {}),
+        ...(filters.includeToolCallOutput !== undefined
+          ? { includeToolCallOutput: filters.includeToolCallOutput }
+          : {}),
+        ...(filters.factTypes ? { factTypes: filters.factTypes } : {}),
+        ...(filters.excludeMentalModels !== undefined
+          ? { excludeMentalModels: filters.excludeMentalModels }
+          : {}),
+        ...(filters.excludeMentalModelIds
+          ? { excludeMentalModelIds: filters.excludeMentalModelIds }
+          : {}),
+        ...composeScopedTagFilter(scopeTags, {
+          ...filters,
+          includeSharedObservations: includeShared,
+        }),
+        ...(filters.signal ? { signal: filters.signal } : {}),
+      });
+      return { bankId, result };
+    },
+
+    async lastRecall(cwd: string) {
+      const config = deps.getConfig();
+      const path = resolveLastRecallPath(cwd, config.recall.lastRecallPath);
+      const snapshot = await readLastRecallSnapshot(cwd, config.recall.lastRecallPath);
+      return { path, snapshot };
+    },
+
+    async recallCleanup(sessionFile: string, prune: boolean) {
+      return prune
+        ? pruneTranscriptRecallBlocks(sessionFile)
+        : scanTranscriptForRecallBlocks(sessionFile);
+    },
+  };
+}

package/node_modules/@luxusai/pi-hindsight/extensions/operations/memory-retain-operations.ts

@@ -0,0 +1,131 @@
+import type { MemoryOperationsDeps } from "./memory-operation-types.js";
+import { flushRetain } from "../queue/queue.js";
+import { resolveOperationBank } from "../banks/bank-selection.js";
+import { explicitMemoryDocumentId } from "../utils/session.js";
+import { createMemoryIdentity, explicitRetainTags } from "./memory-identity.js";
+import { expandObservationScopes } from "../lifecycle/observation-scopes.js";
+import { retainDurably } from "../lifecycle/retain.js";
+import { appendRetainReceipt, listRetainReceipts } from "../lifecycle/retain-receipts.js";
+import {
+  getEffectiveSessionMemoryMode,
+  readSessionMemoryMeta,
+} from "../utils/session-memory-meta.js";
+import type { HindsightObservationScopes, ResolvedConfig, UpdateMode } from "../types.js";
+
+const RESERVED_EXPLICIT_RETAIN_METADATA_KEYS = new Set([
+  "cwd",
+  "pi_session_file",
+  "source",
+  "retainSource",
+]);
+
+function callerMetadata(
+  metadata: Record<string, string> | undefined,
+): Record<string, string> | undefined {
+  if (!metadata) return undefined;
+  const entries = Object.entries(metadata).filter(
+    ([key]) => !RESERVED_EXPLICIT_RETAIN_METADATA_KEYS.has(key),
+  );
+  return entries.length ? Object.fromEntries(entries) : undefined;
+}
+
+export function createRetainOperations(deps: MemoryOperationsDeps) {
+  return {
+    async retainExplicit(args: {
+      cwd: string;
+      sessionFile?: string;
+      content: string;
+      context: string;
+      bank?: string;
+      tags?: string[];
+      entities?: ResolvedConfig["retain"]["entities"];
+      documentId?: string;
+      timestamp?: string;
+      metadata?: Record<string, string>;
+      updateMode?: UpdateMode;
+      observationScopes?: HindsightObservationScopes;
+      documentTags?: string[];
+      async?: boolean;
+    }) {
+      const meta = await readSessionMemoryMeta(args.cwd, args.sessionFile);
+      if (!getEffectiveSessionMemoryMode(meta).retain)
+        throw new Error("Hindsight retain is disabled for this session");
+      const config = deps.getConfig();
+      const bankId = resolveOperationBank({
+        requestedBank: args.bank,
+        config,
+        projectBankId: deps.getProjectBankId(),
+      });
+      const tags = explicitRetainTags(args.cwd, args.sessionFile, [
+        ...(args.tags ?? []),
+        ...meta.tags,
+      ]);
+      const identity = createMemoryIdentity(args.cwd, config, args.sessionFile);
+      const defaultObservationScopes = config.observations.enabled
+        ? expandObservationScopes(config.observations.scopes, {
+            ...identity,
+            projectBankId: bankId,
+          })
+        : [];
+      const observationScopes = args.observationScopes ?? defaultObservationScopes;
+      const result = await retainDurably({
+        cwd: args.cwd,
+        config,
+        client: deps.getClient(),
+        bankId,
+        content: args.content,
+        context: args.context,
+        tags,
+        updateMode: args.updateMode ?? "replace",
+        documentId:
+          args.documentId ??
+          explicitMemoryDocumentId({
+            cwd: args.cwd,
+            ...(args.sessionFile ? { sessionFile: args.sessionFile } : {}),
+            bankId,
+            content: args.content,
+            context: args.context,
+          }),
+        metadata: {
+          ...callerMetadata(args.metadata),
+          cwd: args.cwd,
+          ...(args.sessionFile ? { pi_session_file: args.sessionFile } : {}),
+        },
+        ...(args.timestamp ? { timestamp: args.timestamp } : {}),
+        source: "tool",
+        ...(hasObservationScopes(observationScopes) ? { observationScopes } : {}),
+        ...(args.documentTags?.length ? { documentTags: args.documentTags } : {}),
+        ...(args.entities?.length ? { entities: args.entities } : {}),
+        ...(args.async !== undefined ? { async: args.async } : {}),
+      });
+      const response = { ...result, tags, queued: result.enqueued };
+      await appendRetainReceipt(
+        args.cwd,
+        {
+          bankId: result.bankId,
+          documentId: result.documentId,
+          queueJobId: result.queueJobId,
+          updateMode: result.updateMode,
+          source: "tool",
+          context: args.context,
+          tags,
+          ...(result.outcome ? { outcome: result.outcome } : {}),
+        },
+        { redactSecrets: config.retain.redactSecrets },
+      );
+      return response;
+    },
+
+    async listRetainReceipts(cwd: string, limit?: number) {
+      return listRetainReceipts(cwd, limit);
+    },
+
+    async flush(cwd: string) {
+      return flushRetain(cwd, deps.getConfig(), deps.getClient());
+    },
+  };
+}
+
+function hasObservationScopes(scopes: HindsightObservationScopes): boolean {
+  return typeof scopes === "string" ? scopes.length > 0 : scopes.length > 0;
+}

package/node_modules/@luxusai/pi-hindsight/extensions/operations/memory-scope.ts

@@ -0,0 +1,104 @@
+import type { HindsightTagGroup, TagsMatch, ResolvedConfig } from "../types.js";
+import { recallScopeTags } from "../banks/banking.js";
+import { createMemoryIdentity } from "./memory-identity.js";
+
+export interface MemoryRecallScope {
+  kind: "project" | "global";
+  bankId: string;
+  tagGroups: HindsightTagGroup[];
+}
+
+export function scopeTagsForBank(cwd: string, config: ResolvedConfig, bankId: string): string[] {
+  return config.banks.user.enabled && bankId === config.banks.user.bankId
+    ? ["source:pi"]
+    : recallScopeTags(cwd, config);
+}
+
+export interface ScopedTagFilterInput {
+  tags?: string[];
+  tagsMatch?: TagsMatch;
+  tagGroups?: HindsightTagGroup[];
+  /**
+   * When true, OR exact-empty (shared/untagged) observations with the project scope filter.
+   * Default follows config.scope.includeSharedObservations when composed via recall paths.
+   */
+  includeSharedObservations?: boolean;
+}
+
+/** Hindsight exact-empty leaf: only untagged/shared observation-scope memories. */
+export const SHARED_UNTAGGED_TAG_GROUP: HindsightTagGroup = { tags: [], match: "exact" };
+
+/**
+ * OR project/user scope isolation with exact-empty shared observations.
+ * Used when includeSharedObservations is opted in.
+ */
+export function withSharedObservations(scopeGroup: HindsightTagGroup): HindsightTagGroup {
+  return { or: [scopeGroup, SHARED_UNTAGGED_TAG_GROUP] };
+}
+
+export function composeScopedTagFilter(
+  scopeTags: string[],
+  filters: ScopedTagFilterInput = {},
+): { tagGroups: HindsightTagGroup[] } | Record<string, never> {
+  const includeShared = filters.includeSharedObservations === true;
+  const groups: HindsightTagGroup[] = [];
+
+  if (filters.tags?.length && filters.tagsMatch === "exact") {
+    // "exact" is set-equality: a memory's tag set must equal this group's tags exactly.
+    // AND-ing it with a separate mandatory scope-tag group (any_strict) would require the
+    // memory to have the scope tags AND have exactly the caller's tags, which is
+    // unsatisfiable unless the caller already knows the opaque scope tags. Fold the scope
+    // tags into the exact set instead so scope isolation is preserved and the filter stays
+    // satisfiable.
+    const exactLeaf: HindsightTagGroup = {
+      tags: [...new Set([...scopeTags, ...filters.tags])],
+      match: "exact",
+    };
+    groups.push(includeShared ? withSharedObservations(exactLeaf) : exactLeaf);
+  } else {
+    if (scopeTags.length) {
+      const scopeLeaf: HindsightTagGroup = { tags: scopeTags, match: "any_strict" };
+      groups.push(includeShared ? withSharedObservations(scopeLeaf) : scopeLeaf);
+    } else if (includeShared) {
+      // No project scope tags (unusual) but shared opt-in: only untagged.
+      groups.push(SHARED_UNTAGGED_TAG_GROUP);
+    }
+    if (filters.tags?.length)
+      groups.push({ tags: filters.tags, match: filters.tagsMatch ?? "any_strict" });
+  }
+  if (filters.tagGroups?.length) groups.push(...filters.tagGroups);
+  return groups.length ? { tagGroups: groups } : {};
+}
+
+function scopeTagGroups(scopeTags: string[], includeShared: boolean): HindsightTagGroup[] {
+  const composed = composeScopedTagFilter(scopeTags, {
+    includeSharedObservations: includeShared,
+  });
+  return "tagGroups" in composed ? composed.tagGroups : [];
+}
+
+export function selectMemoryScopes(cwd: string, config: ResolvedConfig): MemoryRecallScope[] {
+  const identity = createMemoryIdentity(cwd, config);
+  const scopes: MemoryRecallScope[] = [];
+  // Shared observations apply only to the coding/project bank (cross-project prefs
+  // inside one bank). Life/user bank keeps source:pi isolation only.
+  const includeShared = config.scope.includeSharedObservations === true;
+
+  if (config.banks.project.enabled) {
+    scopes.push({
+      kind: "project",
+      bankId: identity.projectBankId,
+      tagGroups: scopeTagGroups(identity.projectRecallTags, includeShared),
+    });
+  }
+
+  if (config.banks.user.enabled && config.banks.user.bankId) {
+    scopes.push({
+      kind: "global",
+      bankId: config.banks.user.bankId,
+      tagGroups: scopeTagGroups(identity.globalRecallTags, false),
+    });
+  }
+
+  return scopes;
+}