pi-obsidian-memory 0.0.1 → 0.1.1

package/src/usecases/complete-blank-memory/types.ts

@@ -0,0 +1,28 @@
+import type { Static } from "typebox"
+
+import type {
+  BlankCompletionRefusal,
+  MemoryScope,
+  NoProjectRefusal,
+  UpdateRefusal,
+  VaultCatalogFailure,
+} from "#src/services"
+import type { Succeeded } from "#src/shared"
+import type { MemoryResolutionRefusal } from "#src/usecases/resolve-memory"
+import type { CompleteBlankMemoryRequestSchema } from "./schemas.ts"
+
+export type CompleteBlankMemoryRequest = Static<typeof CompleteBlankMemoryRequestSchema>
+
+export interface CompletedBlank {
+  vault: MemoryScope
+  path: string
+  maintenanceProblems: string[]
+}
+
+export type CompleteBlankMemoryResult =
+  | Succeeded<CompletedBlank>
+  | BlankCompletionRefusal
+  | UpdateRefusal
+  | VaultCatalogFailure
+  | MemoryResolutionRefusal
+  | NoProjectRefusal

package/src/usecases/diagnose-memory/constants.ts

@@ -0,0 +1,3 @@
+export const PROBE_MESSAGE = "Doctor check: does this message need long-term memory?"
+
+export const PROBE_FOLDER = "doctor"

package/src/usecases/diagnose-memory/decision.ts

@@ -0,0 +1,36 @@
+import { decideMemory, type MemoryConfig } from "#src/services"
+import { describeDecisionFailure } from "#src/usecases/relevant-memory"
+import { PROBE_FOLDER, PROBE_MESSAGE } from "./constants.ts"
+import type { DecisionProbe, DecisionReport } from "./types.ts"
+
+export async function checkDecision(
+  configuration: MemoryConfig["decisionModel"],
+  probe: DecisionProbe,
+  signal: AbortSignal,
+): Promise<DecisionReport> {
+  const { provider, model } = configuration
+  if (configuration.provider === "laya") {
+    const { endpoint, maxTokens, headMaxTokens } = configuration
+    const answer = await decideMemory({
+      context: {
+        provider: "laya",
+        endpoint,
+        model: configuration.model,
+        maxTokens,
+        headMaxTokens,
+        signal,
+      },
+      request: { message: PROBE_MESSAGE, project: null, folder: PROBE_FOLDER },
+    })
+    if (answer.succeeded) return { provider, model, status: "ready", detail: `answered at ${endpoint}` }
+    const cause = describeDecisionFailure(answer)
+    return { provider, model, status: "not-answering", problem: `${endpoint} is not answering: ${cause}` }
+  }
+  if (!probe.hasClassifier(provider, model)) {
+    return { provider, model, status: "model-missing", problem: `pi has no ${provider} ${model} classifier model` }
+  }
+  if (!(await probe.hasCredentials(provider))) {
+    return { provider, model, status: "no-credentials", problem: `No API key for ${provider}` }
+  }
+  return { provider, model, status: "ready", detail: "model and API key found" }
+}

package/src/usecases/diagnose-memory/diagnose-memory.ts

@@ -0,0 +1,52 @@
+import { checkChatModels } from "#src/services"
+import {
+  captureMemoryOperationContext,
+  type MemoryOperationContext,
+  memoryAdmissionRefusal,
+  memoryOperationInterruption,
+} from "#src/usecases/operation-context"
+import { resolveCutoffs } from "#src/usecases/relevant-memory"
+import { resolveLeasedMemory } from "#src/usecases/resolve-memory/leased"
+import { checkDecision } from "./decision.ts"
+import { checkEmbeddings } from "./embeddings.ts"
+import type { DiagnosedMemory, DiagnoseMemoryRequest, DiagnoseMemoryResult, ModelReport } from "./types.ts"
+import { reportVault } from "./vault.ts"
+
+export async function diagnoseMemory<TModel>(
+  request: DiagnoseMemoryRequest<TModel>,
+  callerContext: MemoryOperationContext,
+): Promise<DiagnoseMemoryResult> {
+  const context = captureMemoryOperationContext(callerContext)
+  const lease = await context.session.acquire(context.stamp, context.signal)
+  if (!lease) return memoryAdmissionRefusal(context)
+  try {
+    const memory = await resolveLeasedMemory(context)
+    if (!memory.succeeded) return memory
+    const targets = [memory.output.global]
+    let projectMissing = true
+    if (memory.output.project) {
+      targets.push(memory.output.project)
+      projectMissing = false
+    }
+    const vaults: DiagnosedMemory["vaults"] = []
+    for (const target of targets) vaults.push(await reportVault(memory.output, target, context))
+    const { capture, memoryAgent } = memory.output.config
+    const checks = await checkChatModels([capture.model, memoryAgent.model], request.port)
+    const models: ModelReport[] = []
+    const [captureCheck, agentCheck] = checks
+    if (captureCheck) models.push({ role: "capture", check: captureCheck })
+    if (agentCheck) models.push({ role: "memory agent", check: agentCheck })
+    const embeddings = await checkEmbeddings(memory.output.config.embeddings, request.embeddings, context.signal)
+    const decision = await checkDecision(memory.output.config.decisionModel, request.decision, context.signal)
+    const cutoffs = resolveCutoffs(memory.output.config.decisionModel)
+    const interrupted = memoryOperationInterruption(context)
+    if (interrupted) return interrupted
+    const { maxNotesPerFolder } = memory.output.config.limits
+    return {
+      succeeded: true,
+      output: { vaults, projectMissing, maxNotesPerFolder, models, embeddings, decision, cutoffs },
+    }
+  } finally {
+    lease.release()
+  }
+}

package/src/usecases/diagnose-memory/embeddings.ts

@@ -0,0 +1,39 @@
+import type { EmbeddingConfiguration } from "#src/services"
+import { checkLocalModel, localModelDownloadMegabytes } from "#src/usecases/semantic-provider"
+import type { EmbeddingProbe, EmbeddingReport } from "./types.ts"
+
+export async function checkEmbeddings(
+  configuration: EmbeddingConfiguration,
+  probe: EmbeddingProbe,
+  signal: AbortSignal,
+): Promise<EmbeddingReport> {
+  const { provider, model } = configuration
+  if (provider === "local") return checkLocal(configuration, probe, signal)
+  if (await probe.hasCredentials(provider)) return { provider, model, status: "ready" }
+  return { provider, model, status: "no-credentials", problem: `No API key for ${provider}` }
+}
+
+async function checkLocal(
+  configuration: EmbeddingConfiguration,
+  probe: EmbeddingProbe,
+  signal: AbortSignal,
+): Promise<EmbeddingReport> {
+  const { provider, model } = configuration
+  const status = await checkLocalModel(probe.modelCachePath, signal)
+  if (status === "cached") return { provider, model, status: "ready" }
+  if (status === "invalid") {
+    return {
+      provider,
+      model,
+      status: "model-damaged",
+      problem: "The downloaded local model is damaged; remove its folder to download it again",
+    }
+  }
+  const megabytes = localModelDownloadMegabytes()
+  return {
+    provider,
+    model,
+    status: "model-not-downloaded",
+    problem: `The local model is not downloaded yet (about ${megabytes} MB); it is downloaded on the first semantic search`,
+  }
+}

package/src/usecases/diagnose-memory/index.ts

@@ -0,0 +1,5 @@
+export * from "./decision.ts"
+export * from "./diagnose-memory.ts"
+export * from "./embeddings.ts"
+export * from "./types.ts"
+export * from "./vault.ts"

package/src/usecases/diagnose-memory/types.ts

@@ -0,0 +1,86 @@
+import type { ChatModelCheck, ChatModelPort, MemoryScope, VaultDiagnosis } from "#src/services"
+import type { Succeeded } from "#src/shared"
+import type { CutoffReport } from "#src/usecases/relevant-memory"
+import type { MemoryResolutionRefusal } from "#src/usecases/resolve-memory"
+
+export interface DiagnoseMemoryRequest<TModel> {
+  port: ChatModelPort<TModel>
+  embeddings: EmbeddingProbe
+  decision: DecisionProbe
+}
+
+export interface BlankFile {
+  path: string
+  rawHash: string
+  empty: boolean
+}
+
+export interface VaultReport {
+  vault: MemoryScope
+  diagnosis: VaultDiagnosis
+  blanks: BlankFile[]
+  unreadable: string[]
+}
+
+export interface VaultReportFailure {
+  vault: MemoryScope
+  problems: string[]
+}
+
+export interface ModelReport {
+  role: "capture" | "memory agent"
+  check: ChatModelCheck
+}
+
+export interface DiagnosedMemory {
+  vaults: (VaultReport | VaultReportFailure)[]
+  projectMissing: boolean
+  maxNotesPerFolder: number
+  models: ModelReport[]
+  embeddings: EmbeddingReport
+  decision: DecisionReport
+  cutoffs: CutoffReport
+}
+
+export type DiagnoseMemoryResult = Succeeded<DiagnosedMemory> | MemoryResolutionRefusal
+
+export interface EmbeddingProbe {
+  modelCachePath: string
+  hasCredentials(provider: string): Promise<boolean>
+}
+
+export interface EmbeddingReady {
+  provider: string
+  model: string
+  status: "ready"
+}
+
+export interface EmbeddingProblem {
+  provider: string
+  model: string
+  status: "model-not-downloaded" | "model-damaged" | "no-credentials"
+  problem: string
+}
+
+export type EmbeddingReport = EmbeddingReady | EmbeddingProblem
+
+export interface DecisionProbe {
+  hasClassifier(provider: string, model: string): boolean
+  hasCredentials(provider: string): Promise<boolean>
+}
+
+export interface DecisionReady {
+  provider: string
+  model: string
+  status: "ready"
+  detail: string
+}
+
+export interface DecisionProblem {
+  provider: string
+  model: string
+  status: "model-missing" | "no-credentials" | "not-answering"
+  problem: string
+}
+
+export type DecisionReport = DecisionReady | DecisionProblem

package/src/usecases/diagnose-memory/vault.ts

@@ -0,0 +1,33 @@
+import { diagnoseVault, enumerateVault, type InspectedVaultFile, inspectVaultFile } from "#src/services"
+import type { MemoryOperationContext } from "#src/usecases/operation-context"
+import { memoryOperationInterruption } from "#src/usecases/operation-context"
+import type { ResolvedMemory, ResolvedVault } from "#src/usecases/resolve-memory"
+import type { BlankFile, VaultReport, VaultReportFailure } from "./types.ts"
+
+export async function reportVault(
+  memory: ResolvedMemory,
+  target: ResolvedVault,
+  context: MemoryOperationContext,
+): Promise<VaultReport | VaultReportFailure> {
+  const enumerated = await enumerateVault(target.vault)
+  if (!enumerated.succeeded) return { vault: target.scope, problems: enumerated.problems }
+  const { entries } = enumerated.output
+  const unreadable = enumerated.output.failures.map((failure) => `${failure.path}: ${failure.problems.join("; ")}`)
+  const inspected: InspectedVaultFile[] = []
+  for (const entry of entries) {
+    if (entry.kind !== "note") continue
+    if (memoryOperationInterruption(context)) break
+    const file = await inspectVaultFile(target.vault, { path: entry.path })
+    if (file.succeeded) inspected.push(file.output)
+    else unreadable.push(`${entry.path}: ${file.problems.join("; ")}`)
+  }
+  const diagnosis = diagnoseVault({ entries, inspected, limits: memory.config.limits })
+  return { vault: target.scope, diagnosis, blanks: blankFiles(inspected), unreadable }
+}
+
+function blankFiles(inspected: InspectedVaultFile[]): BlankFile[] {
+  return inspected
+    .filter((file) => file.analysis.status === "unclosed")
+    .map((file) => ({ path: file.path, rawHash: file.rawHash, empty: file.text.trim() === "" }))
+    .sort((left, right) => left.path.localeCompare(right.path))
+}

package/src/usecases/export-memory/collect.ts

@@ -0,0 +1,20 @@
+import { collectExportFiles, type VaultExportFile } from "#src/services"
+import type { ResolvedMemory, ResolvedVault } from "#src/usecases/resolve-memory"
+import type { CollectedVaults } from "./types.ts"
+
+export async function collectVaults(memory: ResolvedMemory): Promise<CollectedVaults> {
+  const problems: string[] = []
+  const global = await collectVault(memory.global, problems)
+  let project: VaultExportFile[] | null = null
+  if (memory.project) project = await collectVault(memory.project, problems)
+  return { global, project, problems }
+}
+
+async function collectVault(target: ResolvedVault, problems: string[]): Promise<VaultExportFile[]> {
+  const collected = await collectExportFiles(target.vault)
+  if (collected.succeeded) return collected.output
+  for (const failure of collected.failures) {
+    problems.push(`${target.scope}: ${failure.path}: ${failure.problems.join("; ")}`)
+  }
+  return []
+}

package/src/usecases/export-memory/constants.ts

@@ -0,0 +1,3 @@
+export const EXPORT_EXTENSION = ".zip"
+
+export const FILE_NAME_SEPARATORS = /[\\/]/

package/src/usecases/export-memory/export-memory.ts

@@ -0,0 +1,84 @@
+import { join, resolve } from "node:path"
+
+import { zipSync } from "fflate"
+
+import { canonicalizeAccessPath, exportEntries, vaultAccessRefusal, writeNewFile } from "#src/services"
+import type { PathPlatform } from "#src/usecases/check-vault-access"
+import {
+  captureMemoryOperationContext,
+  type MemoryOperationContext,
+  memoryAdmissionRefusal,
+  memoryOperationInterruption,
+} from "#src/usecases/operation-context"
+import { resolveLeasedMemory } from "#src/usecases/resolve-memory/leased"
+import { collectVaults } from "./collect.ts"
+import { EXPORT_EXTENSION, FILE_NAME_SEPARATORS } from "./constants.ts"
+import type { ExportMemoryRequest, ExportMemoryResult } from "./types.ts"
+
+export async function exportMemory(
+  input: ExportMemoryRequest,
+  callerContext: MemoryOperationContext,
+): Promise<ExportMemoryResult> {
+  const request = { folder: input.folder, fileName: input.fileName, platform: input.platform }
+  const invalid = checkFileName(request.fileName)
+  if (invalid) return { succeeded: false, reason: "invalid", problems: [invalid] }
+  const context = captureMemoryOperationContext(callerContext)
+  const lease = await context.session.acquire(context.stamp, context.signal)
+  if (!lease) return memoryAdmissionRefusal(context)
+  try {
+    return await exportLeasedMemory(request, context)
+  } finally {
+    lease.release()
+  }
+}
+
+async function exportLeasedMemory(
+  request: ExportMemoryRequest,
+  context: MemoryOperationContext,
+): Promise<ExportMemoryResult> {
+  const memory = await resolveLeasedMemory(context)
+  if (!memory.succeeded) return memory
+  const folder = resolve(context.workingFolder, request.folder)
+  if (await isInsideVault(folder, memory.output.protectedRoots, request.platform)) {
+    return {
+      succeeded: false,
+      reason: "inside-vault",
+      problems: [`${folder} is inside a vault; choose another folder`],
+    }
+  }
+  const collected = await collectVaults(memory.output)
+  if (collected.problems.length > 0) {
+    return { succeeded: false, reason: "unreadable-files", problems: collected.problems }
+  }
+  const interrupted = memoryOperationInterruption(context)
+  if (interrupted) return interrupted
+  const entries = exportEntries(collected.global, collected.project)
+  const archive = zipSync(Object.fromEntries(entries.map((entry) => [entry.path, entry.bytes])))
+  const path = join(folder, request.fileName)
+  const written = await writeNewFile(path, archive)
+  if (!written.succeeded) return written
+  const vaults = [memory.output.global.scope]
+  if (collected.project) vaults.push("project")
+  return { succeeded: true, output: { path, files: entries.length, vaults } }
+}
+
+async function isInsideVault(folder: string, vaults: string[], platform: PathPlatform): Promise<boolean> {
+  if (isInside(folder, vaults, platform)) return true
+  const canonical = await canonicalizeAccessPath(folder)
+  if (!canonical.succeeded) return false
+  return isInside(canonical.output, vaults, platform)
+}
+
+function isInside(folder: string, vaults: string[], platform: PathPlatform): boolean {
+  return typeof vaultAccessRefusal({ kind: "file", path: folder }, folder, folder, vaults, platform) === "string"
+}
+
+function checkFileName(fileName: string): string | null {
+  if (fileName === "" || FILE_NAME_SEPARATORS.test(fileName)) {
+    return "The file name must be a plain name with no folders"
+  }
+  if (!fileName.toLowerCase().endsWith(EXPORT_EXTENSION) || fileName.length === EXPORT_EXTENSION.length) {
+    return `The file name must end with ${EXPORT_EXTENSION}`
+  }
+  return null
+}

package/src/usecases/export-memory/index.ts

@@ -0,0 +1,3 @@
+export * from "./collect.ts"
+export * from "./export-memory.ts"
+export * from "./types.ts"

package/src/usecases/export-memory/types.ts

@@ -0,0 +1,28 @@
+import type { MemoryScope, NewFileRefusal, VaultExportFile } from "#src/services"
+import type { Failed, Succeeded } from "#src/shared"
+import type { PathPlatform } from "#src/usecases/check-vault-access"
+import type { MemoryResolutionRefusal } from "#src/usecases/resolve-memory"
+
+export interface ExportMemoryRequest {
+  folder: string
+  fileName: string
+  platform: PathPlatform
+}
+
+export interface ExportedMemory {
+  path: string
+  files: number
+  vaults: MemoryScope[]
+}
+
+export interface ExportRefusal extends Failed {
+  reason: "invalid" | "inside-vault" | "unreadable-files"
+}
+
+export type ExportMemoryResult = Succeeded<ExportedMemory> | MemoryResolutionRefusal | ExportRefusal | NewFileRefusal
+
+export interface CollectedVaults {
+  global: VaultExportFile[]
+  project: VaultExportFile[] | null
+  problems: string[]
+}

package/src/usecases/get-memory/get-memory.ts

@@ -0,0 +1,97 @@
+import { inspectVaultFile, observeVaultPath } from "#src/services"
+import { readLeasedFolder } from "#src/usecases/list-memory/leased"
+import {
+  captureMemoryOperationContext,
+  type MemoryOperationContext,
+  memoryAdmissionRefusal,
+  memoryOperationInterruption,
+  staleMemorySession,
+} from "#src/usecases/operation-context"
+import type { ResolvedVault } from "#src/usecases/resolve-memory"
+import { resolveLeasedMemory, selectMemoryVault } from "#src/usecases/resolve-memory/leased"
+import type { GetMemoryRequest, GetMemoryResult } from "./types.ts"
+
+export async function getMemory(
+  input: GetMemoryRequest,
+  callerContext: MemoryOperationContext,
+): Promise<GetMemoryResult> {
+  const context = captureMemoryOperationContext(callerContext)
+  const request = { vault: input.vault, path: input.path, sourceCallId: input.sourceCallId }
+  const lease = await context.session.acquire(context.stamp, context.signal)
+  if (!lease) return memoryAdmissionRefusal(context)
+  try {
+    const interrupted = memoryOperationInterruption(context)
+    if (interrupted) return interrupted
+    context.session.consumeReceipt(context.stamp, request)
+    const memory = await resolveLeasedMemory(context)
+    const stale = memoryOperationInterruption(context)
+    if (!memory.succeeded) return memory
+    if (stale) return stale
+    const target = selectMemoryVault(memory.output, request.vault)
+    if (!target.succeeded) return target
+    const result = await getLeasedMemory(request, target.output, context)
+    return deliverMemory(result, request, target.output, context)
+  } finally {
+    lease.release()
+  }
+}
+
+async function getLeasedMemory(
+  request: GetMemoryRequest,
+  target: ResolvedVault,
+  context: MemoryOperationContext,
+): Promise<GetMemoryResult> {
+  const entry = await observeVaultPath(target.vault, { path: request.path })
+  const interrupted = memoryOperationInterruption(context)
+  if (interrupted) return interrupted
+  if (!entry.succeeded) return entry
+  if (entry.output.kind === "directory") return readLeasedFolder(target, request.path, context)
+  return getLeasedNote(request, target, context)
+}
+
+async function getLeasedNote(
+  request: GetMemoryRequest,
+  target: ResolvedVault,
+  context: MemoryOperationContext,
+): Promise<GetMemoryResult> {
+  const inspected = await inspectVaultFile(target.vault, { path: request.path })
+  const interrupted = memoryOperationInterruption(context)
+  if (interrupted) return interrupted
+  if (!inspected.succeeded) return inspected
+  const file = inspected.output
+  const analysis = file.analysis
+  if (analysis.status === "unclosed") {
+    return {
+      succeeded: false,
+      reason: "unclosed-frontmatter",
+      file,
+      problems: [...analysis.frontmatterProblems, ...analysis.nameProblems, ...analysis.bodyProblems],
+    }
+  }
+  return { succeeded: true, output: { kind: "note", vault: request.vault, file: { ...file, analysis } } }
+}
+
+function deliverMemory(
+  result: GetMemoryResult,
+  request: GetMemoryRequest,
+  target: ResolvedVault,
+  context: MemoryOperationContext,
+): GetMemoryResult {
+  const interrupted = memoryOperationInterruption(context)
+  if (interrupted) return interrupted
+  if (!result.succeeded || result.output.kind !== "note") return result
+  const file = result.output.file
+  const analysis = file.analysis
+  let id: string | null = null
+  if (analysis.frontmatter) id = analysis.frontmatter.id
+  const remembered = context.session.rememberGet(context.stamp, {
+    ...file,
+    analysis,
+    id,
+    vault: request.vault,
+    canonicalVault: target.vault.path,
+    sourceCallId: request.sourceCallId,
+  })
+  if (!remembered) return staleMemorySession()
+  return result
+}

package/src/usecases/get-memory/index.ts

@@ -0,0 +1,2 @@
+export * from "./get-memory.ts"
+export * from "./types.ts"

package/src/usecases/get-memory/types.ts

@@ -0,0 +1,25 @@
+import type { InspectedVaultFile, MemoryScope, ParsedVaultNote } from "#src/services"
+import type { Failed, Succeeded } from "#src/shared"
+import type { ListMemoryResult } from "#src/usecases/list-memory"
+import type { MemoryAddress } from "#src/usecases/session"
+
+export interface GetMemoryRequest extends MemoryAddress {
+  sourceCallId: string
+}
+
+export interface CompleteMemoryFile extends InspectedVaultFile {
+  analysis: ParsedVaultNote
+}
+
+export interface NoteRead {
+  kind: "note"
+  vault: MemoryScope
+  file: CompleteMemoryFile
+}
+
+export interface UnclosedMemoryRefusal extends Failed {
+  reason: "unclosed-frontmatter"
+  file: InspectedVaultFile
+}
+
+export type GetMemoryResult = Succeeded<NoteRead> | ListMemoryResult | UnclosedMemoryRefusal

package/src/usecases/index.ts

@@ -0,0 +1,25 @@
+export * from "./add-memory/index.ts"
+export * from "./archive-memory/index.ts"
+export * from "./capture-memory/index.ts"
+export * from "./check-shell-edit/index.ts"
+export * from "./check-vault-access/index.ts"
+export * from "./complete-blank-memory/index.ts"
+export * from "./diagnose-memory/index.ts"
+export * from "./export-memory/index.ts"
+export * from "./get-memory/index.ts"
+export * from "./list-memory/index.ts"
+export * from "./load-dont-forget/index.ts"
+export * from "./memory-change/index.ts"
+export * from "./operation-context/index.ts"
+export * from "./registration/index.ts"
+export * from "./relevant-memory/index.ts"
+export * from "./resolve-memory/index.ts"
+export * from "./search-memory/index.ts"
+export * from "./semantic/index.ts"
+export * from "./semantic-port/index.ts"
+export * from "./semantic-provider/index.ts"
+export * from "./session/index.ts"
+export * from "./settings/index.ts"
+export * from "./succeed-memory/index.ts"
+export * from "./synchronize-memory/index.ts"
+export * from "./update-memory/index.ts"

package/src/usecases/list-memory/index.ts

@@ -0,0 +1,2 @@
+export * from "./list-memory.ts"
+export * from "./types.ts"

package/src/usecases/list-memory/leased/index.ts

@@ -0,0 +1,2 @@
+export * from "./read.ts"
+export * from "./types.ts"

package/src/usecases/list-memory/leased/read.ts

@@ -0,0 +1,16 @@
+import { readFolderIndex } from "#src/services"
+import { type MemoryOperationContext, memoryOperationInterruption } from "#src/usecases/operation-context"
+import type { ResolvedVault } from "#src/usecases/resolve-memory"
+import type { ListMemoryResult } from "./types.ts"
+
+export async function readLeasedFolder(
+  target: ResolvedVault,
+  folder: string,
+  context: MemoryOperationContext,
+): Promise<ListMemoryResult> {
+  const result = await readFolderIndex(target.vault, { folder })
+  const interrupted = memoryOperationInterruption(context)
+  if (interrupted) return interrupted
+  if (!result.succeeded) return result
+  return { succeeded: true, output: { kind: "folder", vault: target.scope, ...result.output } }
+}

package/src/usecases/list-memory/leased/types.ts

@@ -0,0 +1,21 @@
+import type {
+  AmbiguousFolderIndex,
+  FolderIndex,
+  MemoryScope,
+  NoProjectRefusal,
+  VaultCatalogFailure,
+} from "#src/services"
+import type { Succeeded } from "#src/shared"
+import type { MemoryResolutionRefusal } from "#src/usecases/resolve-memory"
+
+export interface FolderRead extends FolderIndex {
+  kind: "folder"
+  vault: MemoryScope
+}
+
+export type ListMemoryResult =
+  | Succeeded<FolderRead>
+  | MemoryResolutionRefusal
+  | NoProjectRefusal
+  | VaultCatalogFailure
+  | AmbiguousFolderIndex

package/src/usecases/list-memory/list-memory.ts

@@ -0,0 +1,33 @@
+import { readLeasedFolder } from "#src/usecases/list-memory/leased"
+import {
+  captureMemoryOperationContext,
+  type MemoryOperationContext,
+  memoryAdmissionRefusal,
+  memoryOperationInterruption,
+} from "#src/usecases/operation-context"
+import { resolveLeasedMemory, selectMemoryVault } from "#src/usecases/resolve-memory/leased"
+import type { ListMemoryRequest, ListMemoryResult } from "./types.ts"
+
+export async function listMemory(
+  input: ListMemoryRequest,
+  callerContext: MemoryOperationContext,
+): Promise<ListMemoryResult> {
+  const context = captureMemoryOperationContext(callerContext)
+  const request = { vault: input.vault, folder: input.folder }
+  const lease = await context.session.acquire(context.stamp, context.signal)
+  if (!lease) return memoryAdmissionRefusal(context)
+  try {
+    const memory = await resolveLeasedMemory(context)
+    const interrupted = memoryOperationInterruption(context)
+    if (!memory.succeeded) return memory
+    if (interrupted) return interrupted
+    const target = selectMemoryVault(memory.output, request.vault)
+    if (!target.succeeded) return target
+    const result = await readLeasedFolder(target.output, request.folder, context)
+    const stale = memoryOperationInterruption(context)
+    if (stale) return stale
+    return result
+  } finally {
+    lease.release()
+  }
+}