pi-obsidian-memory 0.0.0 → 0.1.0

package/src/usecases/registration/init.ts

@@ -0,0 +1,94 @@
+import {
+  canonicalizeRegistration,
+  type MemoryConfig,
+  proposeInit,
+  readConfigSnapshot,
+  resolveRegistrationVault,
+} from "#src/services"
+import { captureRegistrationContext } from "./entry.ts"
+import { publishRegistration, registrationInterruption, registrationValidationFailure } from "./publication.ts"
+import type { InitCommitRequest, RegistrationContext, RegistrationResult } from "./types.ts"
+
+export async function initProjectMemory(
+  input: InitCommitRequest,
+  callerContext: RegistrationContext,
+): Promise<RegistrationResult> {
+  const context = captureRegistrationContext(callerContext)
+  const request = { name: input.name, vault: input.vault, expectedHash: input.expectedHash }
+  const lease = await context.session.acquire(context.stamp, context.signal)
+  if (!lease) {
+    return registrationValidationFailure({ succeeded: false, problems: ["registration session admission refused"] })
+  }
+  try {
+    const interrupted = registrationInterruption(context)
+    if (interrupted) return registrationValidationFailure(interrupted)
+    return await prepareProjectRegistration(request, context)
+  } finally {
+    lease.release()
+  }
+}
+
+async function prepareProjectRegistration(
+  request: InitCommitRequest,
+  context: RegistrationContext,
+): Promise<RegistrationResult> {
+  const snapshot = await readConfigSnapshot({ path: context.configPath, platform: context.platform })
+  const interrupted = registrationInterruption(context)
+  if (interrupted) return registrationValidationFailure(interrupted)
+  if (!snapshot.succeeded) return registrationValidationFailure(snapshot)
+  if (snapshot.output.state === "missing") {
+    return registrationValidationFailure({
+      succeeded: false,
+      reason: "not-configured",
+      configPath: context.configPath,
+      problems: ["project registration requires a configured global vault"],
+    })
+  }
+  if (snapshot.output.hash !== request.expectedHash) {
+    return registrationValidationFailure({
+      succeeded: false,
+      reason: "conflict",
+      problems: ["config changed since it was read"],
+      warnings: [],
+    })
+  }
+  const parsed = snapshot.output.lexicalParse
+  if (!parsed.succeeded) return registrationValidationFailure(parsed)
+  return proposeProjectRegistration(request, context, parsed.output)
+}
+
+async function proposeProjectRegistration(
+  request: InitCommitRequest,
+  context: RegistrationContext,
+  config: MemoryConfig,
+): Promise<RegistrationResult> {
+  const valid = await canonicalizeRegistration({
+    config,
+    configPath: context.configPath,
+    indexPath: context.indexPath,
+    platform: context.platform,
+  })
+  const stale = registrationInterruption(context)
+  if (stale) return registrationValidationFailure(stale)
+  if (!valid.succeeded) return registrationValidationFailure(valid)
+  const vault = resolveRegistrationVault({ vault: request.vault, workingFolder: context.workingFolder })
+  if (!vault.succeeded) return registrationValidationFailure(vault)
+  const proposal = proposeInit(
+    { config, folder: context.workingFolder, name: request.name, vault: vault.output },
+    context.platform,
+  )
+  if (!proposal.succeeded) return registrationValidationFailure(proposal)
+  return publishRegistration(
+    {
+      scope: "project",
+      write: {
+        path: context.configPath,
+        platform: context.platform,
+        indexPath: context.indexPath,
+        config: proposal.output,
+        expectedHash: request.expectedHash,
+      },
+    },
+    context,
+  )
+}

package/src/usecases/registration/prepare-init.ts

@@ -0,0 +1,43 @@
+import { basename } from "node:path"
+
+import { type ProjectEntry, readConfigSnapshot, resolveProject } from "#src/services"
+import type { MemoryContext } from "#src/usecases/add-memory"
+import type { InitPreparation, InitPreparationResult, ProjectNameResult } from "./types.ts"
+
+export async function prepareProjectInit(context: MemoryContext): Promise<InitPreparationResult> {
+  const snapshot = await readConfigSnapshot({ path: context.configPath, platform: context.platform })
+  if (!snapshot.succeeded) {
+    return { succeeded: false, reason: "unreadable", configPath: context.configPath, problems: snapshot.problems }
+  }
+  if (snapshot.output.state === "missing") {
+    return {
+      succeeded: false,
+      reason: "not-configured",
+      configPath: context.configPath,
+      problems: ["memory is not configured"],
+    }
+  }
+  const parsed = snapshot.output.lexicalParse
+  if (!parsed.succeeded) {
+    return { succeeded: false, reason: "invalid-config", configPath: context.configPath, problems: parsed.problems }
+  }
+  const registered = resolveProject(parsed.output, context.workingFolder, context.platform)
+  let existing: ProjectEntry | null = null
+  let defaultName = basename(context.workingFolder)
+  if (registered.succeeded) {
+    existing = registered.output
+    defaultName = registered.output.name
+  }
+  const takenNames = parsed.output.projects.filter((project) => project !== existing).map((project) => project.name)
+  return { succeeded: true, output: { expectedHash: snapshot.output.hash, existing, defaultName, takenNames } }
+}
+
+export function checkProjectName(preparation: InitPreparation, answer: string): ProjectNameResult {
+  let name = answer.trim()
+  if (name === "") name = preparation.defaultName
+  const lowered = name.toLowerCase()
+  if (preparation.takenNames.some((taken) => taken.toLowerCase() === lowered)) {
+    return { succeeded: false, problems: [`a project named "${name}" is already registered`] }
+  }
+  return { succeeded: true, output: name }
+}

package/src/usecases/registration/prepare.ts

@@ -0,0 +1,35 @@
+import { prepareSetupDefaults, readConfigSnapshot } from "#src/services"
+import { captureRegistrationContext, captureSelectedModel } from "./entry.ts"
+import { registrationInterruption } from "./publication.ts"
+import type { RegistrationContext, SetupPreparationRequest, SetupPreparationResult } from "./types.ts"
+
+export async function prepareMemorySetup(
+  input: SetupPreparationRequest,
+  callerContext: RegistrationContext,
+): Promise<SetupPreparationResult> {
+  const context = captureRegistrationContext(callerContext)
+  const selectedModel = captureSelectedModel(input.selectedModel)
+  const lease = await context.session.acquire(context.stamp, context.signal)
+  if (!lease) return { succeeded: false, problems: ["registration session admission refused"] }
+  try {
+    const interrupted = registrationInterruption(context)
+    if (interrupted) return interrupted
+    const snapshot = await readConfigSnapshot({ path: context.configPath, platform: context.platform })
+    const stale = registrationInterruption(context)
+    if (stale) return stale
+    if (!snapshot.succeeded) return snapshot
+    const defaults = prepareSetupDefaults(selectedModel)
+    let draft = defaults
+    if (snapshot.output.state === "present") {
+      const repair = snapshot.output.repair
+      draft = {
+        ...repair,
+        capture: { ...repair.capture, model: { ...defaults.capture.model, ...repair.capture.model } },
+        memoryAgent: { model: { ...defaults.memoryAgent.model, ...repair.memoryAgent.model } },
+      }
+    }
+    return { succeeded: true, output: { snapshot: snapshot.output, draft, selectedModel } }
+  } finally {
+    lease.release()
+  }
+}

package/src/usecases/registration/propose.ts

@@ -0,0 +1,34 @@
+import { inspectVaultFolder, proposeSetup, resolveRegistrationVault, setupDisclosures } from "#src/services"
+import type { Failed } from "#src/shared"
+import type { MemoryContext } from "#src/usecases/add-memory"
+import type { SetupProposalRequest, SetupProposalResult, SetupVaultMode } from "./types.ts"
+
+export async function proposeMemorySetup(
+  request: SetupProposalRequest,
+  context: MemoryContext,
+): Promise<SetupProposalResult> {
+  let requested = request.vault.trim()
+  if (requested === "" && request.draft.global.vault) requested = request.draft.global.vault
+  const vault = resolveRegistrationVault({ vault: requested, workingFolder: context.workingFolder })
+  if (!vault.succeeded) return vault
+  const refusal = await vaultFolderRefusal(vault.output, request.mode)
+  if (refusal) return refusal
+  const proposal = proposeSetup({ config: request.draft, vault: vault.output }, context.platform)
+  if (!proposal.succeeded) return proposal
+  return { succeeded: true, output: { config: proposal.output, disclosures: setupDisclosures(proposal.output) } }
+}
+
+async function vaultFolderRefusal(vault: string, mode: SetupVaultMode): Promise<Failed | null> {
+  const folder = await inspectVaultFolder(vault)
+  if (!folder.succeeded) return folder
+  if (folder.output === "not-directory") {
+    return { succeeded: false, problems: [`${vault} is not a folder`] }
+  }
+  if (mode === "create" && folder.output === "populated") {
+    return { succeeded: false, problems: [`${vault} already has files; attach it instead of creating a new vault`] }
+  }
+  if (mode === "attach" && folder.output === "missing") {
+    return { succeeded: false, problems: [`${vault} does not exist; create it instead of attaching`] }
+  }
+  return null
+}

package/src/usecases/registration/publication.ts

@@ -0,0 +1,90 @@
+import {
+  canonicalizeRegistration,
+  checkConfigSnapshot,
+  ensureVaultAssets,
+  targetVault,
+  type VaultBootstrapProgress,
+  writeConfig,
+} from "#src/services"
+import type { Failed } from "#src/shared"
+import type {
+  RegistrationCause,
+  RegistrationContext,
+  RegistrationFailure,
+  RegistrationPublication,
+  RegistrationResult,
+  RegistrationStage,
+} from "./types.ts"
+
+export function registrationInterruption(context: RegistrationContext): Failed | null {
+  if (context.signal.aborted || !context.session.isCurrent(context.stamp)) {
+    return { succeeded: false, problems: ["registration cancelled or session authority changed"] }
+  }
+  return null
+}
+
+export function registrationFailure(
+  stage: RegistrationStage,
+  cause: RegistrationCause,
+  assets: VaultBootstrapProgress,
+): RegistrationFailure {
+  return { succeeded: false, stage, cause, assets, problems: cause.problems }
+}
+
+export function registrationValidationFailure(cause: RegistrationCause): RegistrationFailure {
+  return registrationFailure("validation", cause, {
+    createdRoot: false,
+    created: [],
+    preserved: [],
+    maintenanceProblems: [],
+  })
+}
+
+export async function publishRegistration(
+  publication: RegistrationPublication,
+  context: RegistrationContext,
+): Promise<RegistrationResult> {
+  const { write, scope } = publication
+  const canonical = await canonicalizeRegistration({
+    config: write.config,
+    configPath: write.path,
+    indexPath: write.indexPath,
+    platform: context.platform,
+  })
+  const interrupted = registrationInterruption(context)
+  if (interrupted) return registrationValidationFailure(interrupted)
+  if (!canonical.succeeded) return registrationValidationFailure(canonical)
+  const snapshot = await checkConfigSnapshot(write)
+  const stale = registrationInterruption(context)
+  if (stale) return registrationValidationFailure(stale)
+  if (!snapshot.succeeded) return registrationValidationFailure(snapshot)
+  const target = targetVault(write.config, scope, context.workingFolder, context.platform)
+  if (!target.succeeded) return registrationValidationFailure(target)
+  const assets = await ensureVaultAssets({ ...target.output, limits: write.config.limits })
+  if (!assets.succeeded) return registrationFailure("bootstrap", assets, assets)
+  return commitRegistration(publication, context, assets.output)
+}
+
+async function commitRegistration(
+  publication: RegistrationPublication,
+  context: RegistrationContext,
+  assets: VaultBootstrapProgress,
+): Promise<RegistrationResult> {
+  const interrupted = registrationInterruption(context)
+  if (interrupted) return registrationFailure("config", interrupted, assets)
+  const snapshot = await checkConfigSnapshot(publication.write)
+  const stale = registrationInterruption(context)
+  if (stale) return registrationFailure("config", stale, assets)
+  if (!snapshot.succeeded) return registrationFailure("config", snapshot, assets)
+  const written = await writeConfig(publication.write)
+  if (!written.succeeded) return registrationFailure("config", written, assets)
+  if (context.session.isCurrent(context.stamp)) context.session.invalidate(context.stamp)
+  return {
+    succeeded: true,
+    output: {
+      configHash: written.output.hash,
+      assets,
+      warnings: [...assets.maintenanceProblems, ...written.warnings],
+    },
+  }
+}

package/src/usecases/registration/setup.ts

@@ -0,0 +1,41 @@
+import { resolveRegistrationVault, type WriteConfigRequest } from "#src/services"
+import { captureRegistrationContext, captureSetupCommit } from "./entry.ts"
+import { publishRegistration, registrationInterruption, registrationValidationFailure } from "./publication.ts"
+import type { RegistrationContext, RegistrationResult, SetupCommitRequest } from "./types.ts"
+
+export async function setupMemory(
+  input: SetupCommitRequest,
+  callerContext: RegistrationContext,
+): Promise<RegistrationResult> {
+  const context = captureRegistrationContext(callerContext)
+  const captured = captureSetupCommit(input)
+  if (!captured.succeeded) return registrationValidationFailure(captured)
+  const lease = await context.session.acquire(context.stamp, context.signal)
+  if (!lease) {
+    return registrationValidationFailure({ succeeded: false, problems: ["registration session admission refused"] })
+  }
+  try {
+    const interrupted = registrationInterruption(context)
+    if (interrupted) return registrationValidationFailure(interrupted)
+    return await prepareGlobalRegistration(captured.output, context)
+  } finally {
+    lease.release()
+  }
+}
+
+async function prepareGlobalRegistration(
+  request: SetupCommitRequest,
+  context: RegistrationContext,
+): Promise<RegistrationResult> {
+  const vault = resolveRegistrationVault({ vault: request.config.global.vault, workingFolder: context.workingFolder })
+  if (!vault.succeeded) return registrationValidationFailure(vault)
+  const write: WriteConfigRequest = {
+    path: context.configPath,
+    platform: context.platform,
+    indexPath: context.indexPath,
+    config: { ...request.config, global: { ...request.config.global, vault: vault.output } },
+    expectedHash: request.expectedHash,
+  }
+  if (request.replacementConfirmed) write.replacementConfirmed = true
+  return publishRegistration({ write, scope: "global" }, context)
+}

package/src/usecases/registration/types.ts

@@ -0,0 +1,107 @@
+import type {
+  ChatModelReference,
+  ConfigRefusal,
+  ConfigRepairDraft,
+  ConfigSnapshot,
+  ConfigWriteRefusal,
+  MemoryConfig,
+  MemoryScope,
+  ProjectEntry,
+  SetupDisclosure,
+  VaultBootstrapFailure,
+  VaultBootstrapProgress,
+  WriteConfigRequest,
+} from "#src/services"
+import type { Failed, Succeeded } from "#src/shared"
+import type { MemoryContext } from "#src/usecases/add-memory"
+import type { MemorySession, OperationStamp } from "#src/usecases/session"
+
+export type {
+  ChatModelReference,
+  ConfigRepairDraft,
+  ConfigSnapshot,
+  MemoryConfig,
+  SetupDisclosure,
+  VaultBootstrapProgress,
+} from "#src/services"
+
+export interface RegistrationContext extends MemoryContext {
+  indexPath: string
+  session: MemorySession
+  stamp: OperationStamp
+  signal: AbortSignal
+}
+
+export interface SetupPreparationRequest {
+  selectedModel: ChatModelReference | null
+}
+
+export interface SetupPreparation {
+  snapshot: ConfigSnapshot
+  draft: ConfigRepairDraft
+  selectedModel: ChatModelReference | null
+}
+
+export type SetupPreparationResult = Succeeded<SetupPreparation> | Failed
+
+export interface SetupCommitRequest {
+  config: MemoryConfig
+  expectedHash: string | null
+  replacementConfirmed: boolean
+}
+
+export type SetupCommitCaptureResult = Succeeded<SetupCommitRequest> | Failed
+
+export interface InitCommitRequest {
+  name: string
+  vault: string
+  expectedHash: string
+}
+
+export interface RegistrationOutcome {
+  configHash: string
+  assets: VaultBootstrapProgress
+  warnings: string[]
+}
+
+export type RegistrationStage = "validation" | "bootstrap" | "config"
+export type RegistrationCause = ConfigRefusal | ConfigWriteRefusal | VaultBootstrapFailure | Failed
+
+export interface RegistrationFailure extends Failed {
+  stage: RegistrationStage
+  assets: VaultBootstrapProgress
+  cause: RegistrationCause
+}
+
+export type RegistrationResult = Succeeded<RegistrationOutcome> | RegistrationFailure
+
+export interface RegistrationPublication {
+  write: WriteConfigRequest
+  scope: MemoryScope
+}
+
+export type SetupVaultMode = "create" | "attach"
+
+export interface SetupProposalRequest {
+  draft: ConfigRepairDraft
+  vault: string
+  mode: SetupVaultMode
+}
+
+export interface ProposedSetup {
+  config: MemoryConfig
+  disclosures: SetupDisclosure[]
+}
+
+export type SetupProposalResult = Succeeded<ProposedSetup> | Failed
+
+export interface InitPreparation {
+  expectedHash: string
+  existing: ProjectEntry | null
+  defaultName: string
+  takenNames: string[]
+}
+
+export type InitPreparationResult = Succeeded<InitPreparation> | ConfigRefusal
+
+export type ProjectNameResult = Succeeded<string> | Failed

package/src/usecases/relevant-memory/agent.ts

@@ -0,0 +1,55 @@
+import {
+  type CompletionPort,
+  type MemoryIdentity,
+  type MemoryObservation,
+  type ReadObservation,
+  type RetrievalObservation,
+  refusalObservation,
+  retrieveStep,
+} from "#src/services"
+import { detailOf, observeGet, observeList, observeSearch } from "#src/usecases/capture-memory"
+import { type MemoryOperationContext, memoryOperationInterruption } from "#src/usecases/operation-context"
+import { AGENT_FAILED } from "./constants.ts"
+import type { AgentOutcome, AgentRequest, ReadStep } from "./types.ts"
+
+export async function findNotes(
+  request: AgentRequest,
+  context: MemoryOperationContext,
+  complete: CompletionPort,
+): Promise<AgentOutcome> {
+  const observations: RetrievalObservation[] = []
+  for (;;) {
+    if (memoryOperationInterruption(context)) return { succeeded: false, notice: null }
+    const { agent, query, model } = request
+    const step = await retrieveStep({ context: agent, query, observations, model, signal: context.signal }, complete)
+    if (!step.succeeded && "modelCall" in step) {
+      if (memoryOperationInterruption(context)) return { succeeded: false, notice: null }
+      return { succeeded: false, notice: `${AGENT_FAILED} ${detailOf(step.problems)}` }
+    }
+    if (!step.succeeded) {
+      observations.push(refusalObservation(step.problems))
+      continue
+    }
+    if (step.output.action === "finish") return { succeeded: true, output: chosen(step.output.notes, observations) }
+    observations.push(await observe(step.output, context))
+  }
+}
+
+function observe(action: ReadStep, context: MemoryOperationContext): Promise<MemoryObservation> {
+  if (action.action === "search") return observeSearch(action.vault, action.query, context)
+  if (action.action === "get") return observeGet({ vault: action.vault, path: action.path }, context)
+  return observeList(action.vault, action.folder, context)
+}
+
+function chosen(identities: MemoryIdentity[], observations: RetrievalObservation[]): ReadObservation[] {
+  const reads = observations.filter((observation) => observation.kind === "read")
+  return identities.flatMap((identity) =>
+    reads.filter(
+      (read) =>
+        read.vault === identity.vault &&
+        read.path === identity.path &&
+        read.id === identity.id &&
+        read.hash === identity.hash,
+    ),
+  )
+}

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

@@ -0,0 +1,28 @@
+export const RELEVANT_INTRO =
+  "Relevant long-term memory for this message. This is only part of your memory; use memory_search to find more, and memory_get to read a note in full."
+
+export const SESSION_INTRO =
+  "Relevant long-term memory for this work. This is only part of your memory; use memory_search to find more, and memory_get to read a note in full."
+
+export const NO_CHANGES = { loaded: [], forgotten: [] }
+
+export const BLOCK_SEPARATOR = "\n\n"
+
+export const SESSION_QUERY_PREFIX = "Memory relevant to starting work on"
+
+export const NO_PROJECT = "no registered project"
+
+export const ROUTING_MISSING_HELP =
+  "the Laya server did not say which model answered (it runs with LAYA_JEV_STRICT); run laya-serve without LAYA_JEV_STRICT and bound to 127.0.0.1 with LAYA_HOST"
+
+export const CUTOFFS_MISSING = "Per-message memory is off: the decision model has no cutoff for"
+
+export const CUTOFFS_HELP = "set it with /memory-setup; nothing was added"
+
+export const COULD_NOT_SCORE = "The decision model could not score"
+
+export const AGENT_FAILED = "The memory agent could not find memory:"
+
+export const DECISION_UNAVAILABLE = "The decision model is unavailable, so no memory was added:"
+
+export const SESSION_LOAD_FAILED = "Relevant notes could not be loaded:"

package/src/usecases/relevant-memory/cutoffs.ts

@@ -0,0 +1,29 @@
+import { type DecisionCutoffs, defaultCutoffs, type MemoryConfig } from "#src/services"
+import { CUTOFFS_HELP, CUTOFFS_MISSING } from "./constants.ts"
+import type { CutoffReport, CutoffValue } from "./types.ts"
+
+function cutoffOf(configured: number | undefined, fallback: number | undefined): CutoffValue {
+  if (typeof configured === "number") return { value: configured, source: "config" }
+  if (typeof fallback === "number") return { value: fallback, source: "typesafe" }
+  return { value: null, source: "missing" }
+}
+
+export function resolveCutoffs(config: MemoryConfig["decisionModel"]): CutoffReport {
+  const defaults = defaultCutoffs(config.provider)
+  return {
+    gate: cutoffOf(config.gateThreshold, defaults.gate),
+    relevance: cutoffOf(config.relevanceThreshold, defaults.relevance),
+  }
+}
+
+export function decidingCutoffs(report: CutoffReport): DecisionCutoffs | null {
+  if (typeof report.gate.value !== "number" || typeof report.relevance.value !== "number") return null
+  return { gate: report.gate.value, relevance: report.relevance.value }
+}
+
+export function cutoffsMissingNotice(report: CutoffReport): string {
+  const names: string[] = []
+  if (report.gate.source === "missing") names.push("gateThreshold")
+  if (report.relevance.source === "missing") names.push("relevanceThreshold")
+  return `${CUTOFFS_MISSING} ${names.join(" and ")}; ${CUTOFFS_HELP}`
+}

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

@@ -0,0 +1,102 @@
+import {
+  type CandidateScore,
+  type DecisionContext,
+  type DecisionFailure,
+  type DecisionLimits,
+  type DecisionResult,
+  decideMemory,
+  type MemoryConfig,
+  type ReadObservation,
+  rankCandidates,
+  scoreCandidates,
+} from "#src/services"
+import { COULD_NOT_SCORE, DECISION_UNAVAILABLE, ROUTING_MISSING_HELP } from "./constants.ts"
+import type { JevSource, RankedNotes } from "./types.ts"
+
+export async function decisionContextOf(
+  config: MemoryConfig["decisionModel"],
+  limits: DecisionLimits,
+  jev: JevSource,
+): Promise<DecisionContext | string> {
+  if (config.provider === "laya") {
+    return {
+      provider: "laya",
+      endpoint: config.endpoint,
+      model: config.model,
+      maxTokens: config.maxTokens,
+      headMaxTokens: config.headMaxTokens,
+      ...limits,
+    }
+  }
+  const access = await jev(config.model)
+  if (!access.available) return `${DECISION_UNAVAILABLE} ${access.reason}`
+  return {
+    provider: "typesafe",
+    model: config.model,
+    classifier: access.classifier,
+    ...limits,
+  }
+}
+
+export function decisionNotice(result: DecisionResult): string | null {
+  if (result.succeeded) return null
+  return `${DECISION_UNAVAILABLE} ${describeDecisionFailure(result)}`
+}
+
+export function describeDecisionFailure(failure: DecisionFailure): string {
+  if (failure.code === "routing-missing") return ROUTING_MISSING_HELP
+  if (failure.code !== "http-error" || typeof failure.httpStatus !== "number") return failure.code
+  let text = `${failure.code} (HTTP ${failure.httpStatus})`
+  if (typeof failure.detail === "string") text = `${text}: ${failure.detail}`
+  return text
+}
+
+export function needsMemory(
+  context: DecisionContext,
+  message: string,
+  project: string | null,
+  folder: string,
+): Promise<DecisionResult> {
+  return decideMemory({ context, request: { message, project, folder } })
+}
+
+export async function rankNotes(
+  context: DecisionContext,
+  message: string,
+  notes: ReadObservation[],
+  cutoff: number,
+): Promise<RankedNotes> {
+  const results = await scoreCandidates(
+    context,
+    notes.map((note) => ({
+      message,
+      identity: identityOf(note),
+      candidate: { statement: note.statement, body: note.body },
+    })),
+  )
+  const scores: CandidateScore[] = []
+  let failure: DecisionFailure | null = null
+  let failed = 0
+  results.forEach((result, index) => {
+    const note = notes[index]
+    if (result.succeeded && note) scores.push({ identity: identityOf(note), probability: result.output.probability })
+    else if (!result.succeeded) {
+      failed += 1
+      failure = result
+    }
+  })
+  if (failure && failed === notes.length) return { notes: [], notice: decisionNotice(failure) }
+  const ranked = rankCandidates(scores, cutoff)
+  let notice: string | null = null
+  if (failed > 0) notice = `${COULD_NOT_SCORE} ${failed} of ${notes.length} notes`
+  return { notes: ranked.flatMap((score) => notes.filter((note) => matches(note, score))), notice }
+}
+
+function identityOf(note: ReadObservation): CandidateScore["identity"] {
+  return { vault: note.vault, id: note.id, revision: note.hash }
+}
+
+function matches(note: ReadObservation, score: CandidateScore): boolean {
+  const { identity } = score
+  return note.vault === identity.vault && note.id === identity.id && note.hash === identity.revision
+}

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

@@ -0,0 +1,11 @@
+export * from "./agent.ts"
+export * from "./constants.ts"
+export * from "./cutoffs.ts"
+export * from "./decision.ts"
+export * from "./loaded.ts"
+export * from "./refresh.ts"
+export * from "./retrieve-memory.ts"
+export * from "./schemas.ts"
+export * from "./session-memory.ts"
+export * from "./track-dont-forget.ts"
+export * from "./types.ts"