pi-obsidian-memory 0.0.1 → 0.1.0

package/src/pi/memory-setup/memory-setup.ts

@@ -0,0 +1,153 @@
+import type { MemoryCommand, MemoryPaths, MemoryPiContext } from "#src/pi/context"
+import type { MemorySessionKeeper } from "#src/pi/memory-session"
+import { type CurrentModel, chooseModel, RELOAD_NOTE, runSettingsScreen } from "#src/pi/memory-settings"
+import { describeRegistered, describeRegistrationFailure } from "#src/pi/registration-report"
+import {
+  type ConfigRepairDraft,
+  prepareMemorySettings,
+  prepareMemorySetup,
+  proposeMemorySetup,
+  type RegistrationContext,
+  type SetupPreparation,
+  type SetupVaultMode,
+  setupMemory,
+} from "#src/usecases"
+import {
+  MEMORY_SETUP_DESCRIPTION,
+  REPAIR_CONFIRM_LINE,
+  REPAIR_TITLE,
+  REPLACE_LINE,
+  SETUP_AGENT_MODEL_TITLE,
+  SETUP_ATTACH_OPTION,
+  SETUP_CANCELLED,
+  SETUP_CAPTURE_MODEL_TITLE,
+  SETUP_CREATE_OPTION,
+  SETUP_DONE,
+  SETUP_KEEP_VAULT_TITLE,
+  SETUP_MODE_TITLE,
+  SETUP_NO_MODEL,
+  SETUP_VAULT_PLACEHOLDER,
+  SETUP_VAULT_TITLE,
+} from "./constants.ts"
+import { disclosureText } from "./disclosure.ts"
+import type { VaultStep } from "./types.ts"
+
+export function memorySetupCommand(paths: MemoryPaths, sessions: MemorySessionKeeper): MemoryCommand {
+  return {
+    description: MEMORY_SETUP_DESCRIPTION,
+    async handler(_args, ctx) {
+      if (!ctx.hasUI) return
+      const { registration } = sessions.registrationFlow(ctx, paths)
+      await runMemorySetup(ctx, registration)
+    },
+  }
+}
+
+async function runMemorySetup(ctx: MemoryPiContext, registration: RegistrationContext): Promise<void> {
+  const settings = await prepareMemorySettings(registration)
+  if (settings.succeeded) {
+    await runSettingsScreen(ctx, { registration, changeGlobalVault: (context) => changeVault(ctx, context) })
+    return
+  }
+  await runFirstSetup(ctx, registration)
+}
+
+async function runFirstSetup(ctx: MemoryPiContext, registration: RegistrationContext): Promise<void> {
+  const preparation = await prepareSetup(ctx, registration)
+  if (!preparation) return
+  if (!(await confirmRepair(ctx, preparation.draft))) return cancelled(ctx)
+  if (noModelToChoose(ctx, preparation.draft)) return
+  const draft = await chooseModels(ctx, preparation.draft)
+  if (!draft) return cancelled(ctx)
+  await commitVault(ctx, registration, { snapshot: preparation.snapshot, draft })
+}
+
+async function changeVault(ctx: MemoryPiContext, registration: RegistrationContext): Promise<void> {
+  const preparation = await prepareSetup(ctx, registration)
+  if (!preparation) return
+  await commitVault(ctx, registration, preparation)
+}
+
+async function commitVault(
+  ctx: MemoryPiContext,
+  registration: RegistrationContext,
+  preparation: VaultStep,
+): Promise<void> {
+  const { snapshot, draft } = preparation
+  const mode = await askMode(ctx, draft)
+  if (!mode) return cancelled(ctx)
+  const vault = await askVault(ctx, draft)
+  if (typeof vault !== "string") return cancelled(ctx)
+  const proposal = await proposeMemorySetup({ draft, vault, mode }, registration)
+  if (!proposal.succeeded) return ctx.ui.notify(proposal.problems.join("\n"), "error")
+  ctx.ui.notify(disclosureText(proposal.output.disclosures), "warning")
+  const result = await setupMemory(
+    {
+      config: proposal.output.config,
+      expectedHash: snapshot.hash,
+      replacementConfirmed: draft.replacementRequired,
+    },
+    registration,
+  )
+  if (!result.succeeded) return ctx.ui.notify(describeRegistrationFailure(result), "error")
+  const saved = describeRegistered(`${SETUP_DONE} ${proposal.output.config.global.vault}`, result.output)
+  ctx.ui.notify(`${saved}\n${RELOAD_NOTE}`, "info")
+}
+
+function cancelled(ctx: MemoryPiContext): void {
+  ctx.ui.notify(SETUP_CANCELLED, "info")
+}
+
+async function prepareSetup(ctx: MemoryPiContext, registration: RegistrationContext): Promise<SetupPreparation | null> {
+  const preparation = await prepareMemorySetup({ selectedModel: null }, registration)
+  if (!preparation.succeeded) {
+    ctx.ui.notify(preparation.problems.join("\n"), "error")
+    return null
+  }
+  return preparation.output
+}
+
+function modelResolved(model: ConfigRepairDraft["capture"]["model"]): boolean {
+  return typeof model.provider === "string" && typeof model.id === "string"
+}
+
+function noModelToChoose(ctx: MemoryPiContext, draft: ConfigRepairDraft): boolean {
+  if (ctx.modelRegistry.getAvailable().length > 0) return false
+  if (modelResolved(draft.capture.model) && modelResolved(draft.memoryAgent.model)) return false
+  ctx.ui.notify(SETUP_NO_MODEL, "error")
+  return true
+}
+
+function inUseOf(ctx: MemoryPiContext): CurrentModel {
+  if (!ctx.model) return {}
+  return { provider: ctx.model.provider, id: ctx.model.id }
+}
+
+async function chooseModels(ctx: MemoryPiContext, draft: ConfigRepairDraft): Promise<ConfigRepairDraft | null> {
+  const capture = await chooseModel(ctx, SETUP_CAPTURE_MODEL_TITLE, draft.capture.model, inUseOf(ctx))
+  if (!capture) return null
+  const agent = await chooseModel(ctx, SETUP_AGENT_MODEL_TITLE, draft.memoryAgent.model, {})
+  if (!agent) return null
+  return { ...draft, capture: { ...draft.capture, model: capture }, memoryAgent: { model: agent } }
+}
+
+async function confirmRepair(ctx: MemoryPiContext, draft: ConfigRepairDraft): Promise<boolean> {
+  if (draft.problems.length === 0 && !draft.replacementRequired) return true
+  const lines = draft.problems.map((problem) => `- ${problem}`)
+  if (draft.replacementRequired) lines.push(REPLACE_LINE)
+  return ctx.ui.confirm(REPAIR_TITLE, [...lines, REPAIR_CONFIRM_LINE].join("\n"))
+}
+
+async function askMode(ctx: MemoryPiContext, draft: ConfigRepairDraft): Promise<SetupVaultMode | null> {
+  let options = [SETUP_CREATE_OPTION, SETUP_ATTACH_OPTION]
+  if (draft.global.vault) options = [SETUP_ATTACH_OPTION, SETUP_CREATE_OPTION]
+  const answer = await ctx.ui.select(SETUP_MODE_TITLE, options)
+  if (answer === SETUP_CREATE_OPTION) return "create"
+  if (answer === SETUP_ATTACH_OPTION) return "attach"
+  return null
+}
+
+function askVault(ctx: MemoryPiContext, draft: ConfigRepairDraft): Promise<string | undefined> {
+  if (draft.global.vault) return ctx.ui.input(SETUP_KEEP_VAULT_TITLE, draft.global.vault)
+  return ctx.ui.input(SETUP_VAULT_TITLE, SETUP_VAULT_PLACEHOLDER)
+}

package/src/pi/memory-setup/types.ts

@@ -0,0 +1,6 @@
+import type { ConfigRepairDraft, SetupPreparation } from "#src/usecases"
+
+export interface VaultStep {
+  snapshot: SetupPreparation["snapshot"]
+  draft: ConfigRepairDraft
+}

package/src/pi/memory-succeed/constants.ts

@@ -0,0 +1,10 @@
+export const MEMORY_SUCCEED_TOOL_NAME = "memory_succeed"
+
+export const MEMORY_SUCCEED_TOOL_LABEL = "Memory succeed"
+
+export const MEMORY_SUCCEED_TOOL_DESCRIPTION =
+  "Use only when the user explicitly asks to replace a memory that stopped being true or was resolved. Read it with memory_get first."
+
+export const REPLACED_PREFIX = "Replaced in"
+
+export const NEW_NOTE_LABEL = "new note:"

package/src/pi/memory-succeed/index.ts

@@ -0,0 +1,4 @@
+export * from "./constants.ts"
+export * from "./memory-succeed.ts"
+export * from "./schemas.ts"
+export * from "./types.ts"

package/src/pi/memory-succeed/memory-succeed.ts

@@ -0,0 +1,34 @@
+import { type ChangeResponse, reportFailure, reportSuccess } from "#src/pi/change-report"
+import type { MemoryPaths } from "#src/pi/context"
+import { type MemorySessionKeeper, noSessionResponse } from "#src/pi/memory-session"
+import { succeedMemory } from "#src/usecases"
+import {
+  MEMORY_SUCCEED_TOOL_DESCRIPTION,
+  MEMORY_SUCCEED_TOOL_LABEL,
+  MEMORY_SUCCEED_TOOL_NAME,
+  NEW_NOTE_LABEL,
+  REPLACED_PREFIX,
+} from "./constants.ts"
+import { MemorySucceedParamsSchema } from "./schemas.ts"
+import type { MemorySucceedTool } from "./types.ts"
+
+export function memorySucceedTool(paths: MemoryPaths, sessions: MemorySessionKeeper): MemorySucceedTool {
+  return {
+    name: MEMORY_SUCCEED_TOOL_NAME,
+    label: MEMORY_SUCCEED_TOOL_LABEL,
+    description: MEMORY_SUCCEED_TOOL_DESCRIPTION,
+    parameters: MemorySucceedParamsSchema,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx): Promise<ChangeResponse> {
+      const context = sessions.currentOperation(ctx.cwd, paths, signal)
+      if (!context) return noSessionResponse()
+      const { vault, path, folder, statement, type, body, dontForget } = params
+      const result = await succeedMemory({ vault, path, folder, draft: { statement, type, body, dontForget } }, context)
+      if (!result.succeeded) return reportFailure(result, path)
+      const { archivedPath, successorPath, maintenanceProblems } = result.output
+      return reportSuccess(
+        `${REPLACED_PREFIX} ${result.output.vault}: ${archivedPath}; ${NEW_NOTE_LABEL} ${successorPath}`,
+        maintenanceProblems,
+      )
+    },
+  }
+}

package/src/pi/memory-succeed/schemas.ts

@@ -0,0 +1,30 @@
+import Type from "typebox"
+
+import { SucceedMemoryRequestSchema } from "#src/usecases"
+
+export const MemorySucceedParamsSchema = Type.Object(
+  {
+    vault: Type.With(SucceedMemoryRequestSchema.properties.vault, {
+      description: "global: about the user. project: about this project. The vault the old note was read from.",
+    }),
+    path: Type.With(SucceedMemoryRequestSchema.properties.path, {
+      description: "The old note's path, exactly as read with memory_get.",
+    }),
+    folder: Type.With(SucceedMemoryRequestSchema.properties.folder, {
+      description: "Subject folder of the new note, in English, from general to specific. Reuse a folder that exists.",
+    }),
+    statement: Type.With(SucceedMemoryRequestSchema.properties.draft.properties.statement, {
+      description: "The new note's name, in English: one short statement saying what is true now.",
+    }),
+    type: Type.With(SucceedMemoryRequestSchema.properties.draft.properties.type, {
+      description: "The kind of memory of the new note.",
+    }),
+    body: Type.With(SucceedMemoryRequestSchema.properties.draft.properties.body, {
+      description: "The full detail of the new note, in English. Never empty.",
+    }),
+    dontForget: Type.With(SucceedMemoryRequestSchema.properties.draft.properties.dontForget, {
+      description: "true only when the new note must be loaded in every session.",
+    }),
+  },
+  { additionalProperties: false },
+)

package/src/pi/memory-succeed/types.ts

@@ -0,0 +1,8 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent"
+import type { Static } from "typebox"
+
+import type { MemorySucceedParamsSchema } from "./schemas.ts"
+
+export type MemorySucceedParams = Static<typeof MemorySucceedParamsSchema>
+
+export type MemorySucceedTool = ToolDefinition<typeof MemorySucceedParamsSchema, undefined>

package/src/pi/memory-update/constants.ts

@@ -0,0 +1,8 @@
+export const MEMORY_UPDATE_TOOL_NAME = "memory_update"
+
+export const MEMORY_UPDATE_TOOL_LABEL = "Memory update"
+
+export const MEMORY_UPDATE_TOOL_DESCRIPTION =
+  "Use only when the user explicitly asks to change a memory. Read it with memory_get first."
+
+export const UPDATED_PREFIX = "Updated in"

package/src/pi/memory-update/index.ts

@@ -0,0 +1,4 @@
+export * from "./constants.ts"
+export * from "./memory-update.ts"
+export * from "./schemas.ts"
+export * from "./types.ts"

package/src/pi/memory-update/memory-update.ts

@@ -0,0 +1,29 @@
+import { type ChangeResponse, reportFailure, reportSuccess } from "#src/pi/change-report"
+import type { MemoryPaths } from "#src/pi/context"
+import { type MemorySessionKeeper, noSessionResponse } from "#src/pi/memory-session"
+import { updateMemory } from "#src/usecases"
+import {
+  MEMORY_UPDATE_TOOL_DESCRIPTION,
+  MEMORY_UPDATE_TOOL_LABEL,
+  MEMORY_UPDATE_TOOL_NAME,
+  UPDATED_PREFIX,
+} from "./constants.ts"
+import { MemoryUpdateParamsSchema } from "./schemas.ts"
+import type { MemoryUpdateTool } from "./types.ts"
+
+export function memoryUpdateTool(paths: MemoryPaths, sessions: MemorySessionKeeper): MemoryUpdateTool {
+  return {
+    name: MEMORY_UPDATE_TOOL_NAME,
+    label: MEMORY_UPDATE_TOOL_LABEL,
+    description: MEMORY_UPDATE_TOOL_DESCRIPTION,
+    parameters: MemoryUpdateParamsSchema,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx): Promise<ChangeResponse> {
+      const context = sessions.currentOperation(ctx.cwd, paths, signal)
+      if (!context) return noSessionResponse()
+      const result = await updateMemory(params, context)
+      if (!result.succeeded) return reportFailure(result, params.path)
+      const { vault, path, maintenanceProblems } = result.output
+      return reportSuccess(`${UPDATED_PREFIX} ${vault}: ${path}`, maintenanceProblems)
+    },
+  }
+}

package/src/pi/memory-update/schemas.ts

@@ -0,0 +1,24 @@
+import Type from "typebox"
+
+import { UpdateMemoryRequestSchema } from "#src/usecases"
+
+export const MemoryUpdateParamsSchema = Type.Object(
+  {
+    vault: Type.With(UpdateMemoryRequestSchema.properties.vault, {
+      description: "global: about the user. project: about this project. The vault the note was read from.",
+    }),
+    path: Type.With(UpdateMemoryRequestSchema.properties.path, {
+      description: "The note's path, exactly as read with memory_get. A new name needs a new note, not an update.",
+    }),
+    body: Type.With(UpdateMemoryRequestSchema.properties.body, {
+      description: "The full new body, in English. Never empty.",
+    }),
+    type: Type.With(UpdateMemoryRequestSchema.properties.type, {
+      description: "Only when the kind of memory changes; leave out to keep it.",
+    }),
+    dontForget: Type.With(UpdateMemoryRequestSchema.properties.dontForget, {
+      description: "true to load it in every session, false to stop; leave out to keep it.",
+    }),
+  },
+  { additionalProperties: false },
+)

package/src/pi/memory-update/types.ts

@@ -0,0 +1,8 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent"
+import type { Static } from "typebox"
+
+import type { MemoryUpdateParamsSchema } from "./schemas.ts"
+
+export type MemoryUpdateParams = Static<typeof MemoryUpdateParamsSchema>
+
+export type MemoryUpdateTool = ToolDefinition<typeof MemoryUpdateParamsSchema, undefined>

package/src/pi/paths/constants.ts

@@ -0,0 +1,7 @@
+export const MEMORY_FOLDER_NAME = "pi-obsidian-memory"
+
+export const CONFIG_FILE_NAME = "config.json"
+
+export const INDEX_FOLDER_NAME = "index"
+
+export const MODEL_FOLDER_NAME = "models"

package/src/pi/paths/index.ts

@@ -0,0 +1,2 @@
+export * from "./paths.ts"
+export * from "./platform.ts"

package/src/pi/paths/paths.ts

@@ -0,0 +1,15 @@
+import { join } from "node:path"
+
+import { CONFIG_FILE_NAME, INDEX_FOLDER_NAME, MEMORY_FOLDER_NAME, MODEL_FOLDER_NAME } from "./constants.ts"
+
+export function memoryConfigPath(agentDir: string): string {
+  return join(agentDir, MEMORY_FOLDER_NAME, CONFIG_FILE_NAME)
+}
+
+export function memoryModelCachePath(agentDir: string): string {
+  return join(agentDir, MEMORY_FOLDER_NAME, MODEL_FOLDER_NAME)
+}
+
+export function memoryIndexPath(agentDir: string): string {
+  return join(agentDir, MEMORY_FOLDER_NAME, INDEX_FOLDER_NAME)
+}

package/src/pi/paths/platform.ts

@@ -0,0 +1,7 @@
+import type { PathPlatform } from "#src/usecases"
+
+export function hostPathPlatform(host: NodeJS.Platform): PathPlatform {
+  if (host === "win32") return "win32"
+  if (host === "darwin") return "darwin"
+  return "linux"
+}

package/src/pi/registrar.ts

@@ -0,0 +1,25 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
+
+import { CURSOR_TYPE } from "#src/pi/capture"
+import type { ExtensionRegistrar } from "./types.ts"
+
+export function registrarFor(pi: ExtensionAPI): ExtensionRegistrar {
+  return {
+    registerAddTool: (tool) => pi.registerTool(tool),
+    registerSearchTool: (tool) => pi.registerTool(tool),
+    registerGetTool: (tool) => pi.registerTool(tool),
+    registerUpdateTool: (tool) => pi.registerTool(tool),
+    registerArchiveTool: (tool) => pi.registerTool(tool),
+    registerSucceedTool: (tool) => pi.registerTool(tool),
+    registerCommand: (name, command) => pi.registerCommand(name, command),
+    onSessionStart: (handler) => pi.on("session_start", handler),
+    onBeforeAgentStart: (handler) => pi.on("before_agent_start", handler),
+    onToolCall: (handler) => pi.on("tool_call", handler),
+    onShellToolCall: (handler) => pi.on("tool_call", handler),
+    onMessageEnd: (handler) => pi.on("message_end", handler),
+    onTurnEnd: (handler) => pi.on("turn_end", handler),
+    onBeforeCompact: (handler) => pi.on("session_before_compact", handler),
+    appendCursor: (data) => pi.appendEntry(CURSOR_TYPE, data),
+    onSessionShutdown: (handler) => pi.on("session_shutdown", handler),
+  }
+}

package/src/pi/registration-report/constants.ts

@@ -0,0 +1,13 @@
+export const VAULT_CREATED_LINE = "Vault folder created."
+
+export const CREATED_HEADING = "Created:"
+
+export const PRESERVED_HEADING = "Kept as they were:"
+
+export const WARNINGS_HEADING = "Warnings:"
+
+export const PROBLEMS_HEADING = "Not changed. Problems:"
+
+export const BOOTSTRAP_STAGE_LINE = "Stopped while preparing the vault; the config was not written."
+
+export const CONFIG_STAGE_LINE = "The vault is ready but the config was not written."

package/src/pi/registration-report/index.ts

@@ -0,0 +1,2 @@
+export * from "./constants.ts"
+export * from "./report.ts"

package/src/pi/registration-report/report.ts

@@ -0,0 +1,26 @@
+import type { RegistrationFailure, RegistrationOutcome } from "#src/usecases"
+import {
+  BOOTSTRAP_STAGE_LINE,
+  CONFIG_STAGE_LINE,
+  CREATED_HEADING,
+  PRESERVED_HEADING,
+  PROBLEMS_HEADING,
+  VAULT_CREATED_LINE,
+  WARNINGS_HEADING,
+} from "./constants.ts"
+
+export function describeRegistered(headline: string, outcome: RegistrationOutcome): string {
+  const lines = [headline]
+  if (outcome.assets.createdRoot) lines.push(VAULT_CREATED_LINE)
+  if (outcome.assets.created.length > 0) lines.push(`${CREATED_HEADING} ${outcome.assets.created.join(", ")}`)
+  if (outcome.assets.preserved.length > 0) lines.push(`${PRESERVED_HEADING} ${outcome.assets.preserved.join(", ")}`)
+  if (outcome.warnings.length > 0) lines.push(WARNINGS_HEADING, ...outcome.warnings.map((warning) => `- ${warning}`))
+  return lines.join("\n")
+}
+
+export function describeRegistrationFailure(failure: RegistrationFailure): string {
+  const lines = [PROBLEMS_HEADING, ...failure.problems.map((problem) => `- ${problem}`)]
+  if (failure.stage === "bootstrap") lines.push(BOOTSTRAP_STAGE_LINE)
+  if (failure.stage === "config") lines.push(CONFIG_STAGE_LINE)
+  return lines.join("\n")
+}

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

@@ -0,0 +1,3 @@
+export const RELEVANT_MESSAGE_TYPE = "obsidian-memory-relevant"
+
+export const JEV_MISSING = "pi has no Jev model (typesafe jev-latest) in its catalog"

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

@@ -0,0 +1,4 @@
+export * from "./constants.ts"
+export * from "./prompt.ts"
+export * from "./runtime.ts"
+export * from "./types.ts"

package/src/pi/relevant-memory/prompt.ts

@@ -0,0 +1,23 @@
+import type { ClassifierPrompt } from "#src/pi/context"
+import type { JevPrompt, JevQuestion } from "./types.ts"
+
+function questionOf(question: JevQuestion) {
+  return {
+    type: question.type,
+    instructions: question.instructions,
+    criteria: { true: question.criteria.true, false: question.criteria.false },
+  }
+}
+
+function stateOf(state: JevPrompt["state"]) {
+  if ("candidate" in state) {
+    return { message: state.message, candidate: { statement: state.candidate.statement, body: state.candidate.body } }
+  }
+  return { message: state.message, project: state.project, folder: state.folder }
+}
+
+export function classifierPrompt(prompt: JevPrompt): ClassifierPrompt {
+  const { state, questions } = prompt
+  if ("needed" in questions) return { state: stateOf(state), questions: { needed: questionOf(questions.needed) } }
+  return { state: stateOf(state), questions: { relevant: questionOf(questions.relevant) } }
+}

package/src/pi/relevant-memory/runtime.ts

@@ -0,0 +1,88 @@
+import { Value } from "typebox/value"
+
+import { type MemoryPiContext, STATUS_SEARCHING, withMemoryStatus } from "#src/pi/context"
+import type { BeforeAgentStartHandler } from "#src/pi/memory-block"
+import { type JevSource, LoadedChangesSchema, loadSessionMemory, retrieveMemory } from "#src/usecases"
+import { JEV_MISSING, RELEVANT_MESSAGE_TYPE } from "./constants.ts"
+import { classifierPrompt } from "./prompt.ts"
+import type { RelevantMemoryDeps } from "./types.ts"
+
+export class RelevantMemoryRuntime {
+  #deps: RelevantMemoryDeps
+  #told = new Set<string>()
+
+  constructor(deps: RelevantMemoryDeps) {
+    this.#deps = deps
+  }
+
+  reset(): void {
+    this.#told = new Set<string>()
+  }
+
+  restore(ctx: MemoryPiContext): void {
+    const loaded = this.#deps.sessions.loaded()
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type !== "custom_message" || entry.customType !== RELEVANT_MESSAGE_TYPE) continue
+      if (Value.Check(LoadedChangesSchema, entry.details)) loaded.apply(entry.details)
+    }
+  }
+
+  async sessionText(ctx: MemoryPiContext): Promise<string | null> {
+    const operation = this.#deps.sessions.retrievalOperation(ctx.cwd, this.#deps.paths)
+    if (!operation) return null
+    const result = await loadSessionMemory(operation, {
+      complete: this.#deps.completionOf(ctx),
+      loaded: this.#deps.sessions.loaded(),
+    })
+    if (!result.succeeded) return null
+    this.tell(ctx, result.output.notices)
+    return result.output.text
+  }
+
+  beforeAgentStart(): BeforeAgentStartHandler {
+    return async (event, ctx) => {
+      if (event.messageType !== "user") return undefined
+      const operation = this.#deps.sessions.retrievalOperation(ctx.cwd, this.#deps.paths)
+      if (!operation) return undefined
+      const result = await withMemoryStatus(ctx, STATUS_SEARCHING, () =>
+        retrieveMemory({ message: event.prompt }, operation, {
+          complete: this.#deps.completionOf(ctx),
+          jev: this.#jevFor(ctx),
+          loaded: this.#deps.sessions.loaded(),
+        }),
+      )
+      if (!result.succeeded) return undefined
+      this.tell(ctx, result.output.notices)
+      if (typeof result.output.text !== "string") return undefined
+      return {
+        message: {
+          customType: RELEVANT_MESSAGE_TYPE,
+          content: result.output.text,
+          display: false,
+          details: result.output.changes,
+        },
+      }
+    }
+  }
+
+  tell(ctx: MemoryPiContext, notices: string[]): void {
+    for (const notice of notices) {
+      if (this.#told.has(notice)) continue
+      this.#told.add(notice)
+      if (ctx.hasUI) ctx.ui.notify(notice, "warning")
+    }
+  }
+
+  #jevFor(ctx: MemoryPiContext): JevSource {
+    return async (modelId) => {
+      const model = ctx.modelRegistry.findOfType("classifier", "typesafe", modelId)
+      if (!model) return { available: false, reason: JEV_MISSING }
+      return {
+        available: true,
+        classifier: {
+          classify: (request) => ctx.modelRegistry.classify(model, classifierPrompt(request.context), request.options),
+        },
+      }
+    }
+  }
+}

package/src/pi/relevant-memory/types.ts

@@ -0,0 +1,14 @@
+import type { CompletionFactory } from "#src/pi/capture"
+import type { MemoryPaths } from "#src/pi/context"
+import type { MemorySessionKeeper } from "#src/pi/memory-session"
+import type { BoolQuestion, DecisionPrompt } from "#src/usecases"
+
+export interface RelevantMemoryDeps {
+  paths: MemoryPaths
+  sessions: MemorySessionKeeper
+  completionOf: CompletionFactory
+}
+
+export type JevPrompt = DecisionPrompt
+
+export type JevQuestion = BoolQuestion

package/src/pi/semantic/constants.ts

@@ -0,0 +1,3 @@
+export const MODEL_INVALID = "the downloaded local model is damaged; remove its folder to download it again"
+
+export const SHUTDOWN_FAILED = "The local search model did not shut down cleanly:"

package/src/pi/semantic/index.ts

@@ -0,0 +1,2 @@
+export * from "./constants.ts"
+export * from "./runtime.ts"

package/src/pi/semantic/runtime.ts

@@ -0,0 +1,59 @@
+import type { MemoryPiContext } from "#src/pi/context"
+import {
+  createRemoteSemantic,
+  type LocalModelAccess,
+  type LocalSemantic,
+  localModelAccess,
+  type SemanticPort,
+  type SemanticSource,
+} from "#src/usecases"
+import { MODEL_INVALID, SHUTDOWN_FAILED } from "./constants.ts"
+
+export class SemanticRuntime {
+  #context: MemoryPiContext | null = null
+  #local: LocalSemantic | null = null
+  #modelCachePath: string
+  #access: LocalModelAccess = localModelAccess
+
+  constructor(modelCachePath: string, access?: LocalModelAccess) {
+    this.#modelCachePath = modelCachePath
+    if (access) this.#access = access
+  }
+
+  readonly source: SemanticSource = (configuration) => {
+    if (configuration.provider === "local") return this.#localPort()
+    return this.#remotePort(configuration.provider)
+  }
+
+  attach(context: MemoryPiContext): void {
+    this.#context = context
+  }
+
+  async shutdown(): Promise<void> {
+    const local = this.#local
+    const context = this.#context
+    this.#local = null
+    this.#context = null
+    if (!local) return
+    try {
+      await local.dispose()
+    } catch (error) {
+      if (!(error instanceof Error)) throw error
+      if (context?.hasUI) context.ui.notify(`${SHUTDOWN_FAILED} ${error.message}`, "warning")
+    }
+  }
+
+  async #localPort(): Promise<SemanticPort> {
+    if (this.#local) return this.#local.port
+    const status = await this.#access.check(this.#modelCachePath, new AbortController().signal)
+    if (status === "invalid") return { available: false, reason: MODEL_INVALID }
+    this.#local = this.#access.create({ cachePath: this.#modelCachePath })
+    return this.#local.port
+  }
+
+  async #remotePort(provider: "openai" | "google"): Promise<SemanticPort> {
+    const apiKey = await this.#context?.modelRegistry.getApiKeyForProvider(provider)
+    if (typeof apiKey !== "string" || apiKey === "") return { available: false, reason: `no API key for ${provider}` }
+    return createRemoteSemantic(provider, apiKey)
+  }
+}

package/src/pi/session-start/constants.ts

@@ -0,0 +1,7 @@
+export const NO_MEMORY_NOTICE = "No memory is configured yet. Run /memory-setup to choose the global vault."
+
+export const INVALID_CONFIG_NOTICE = "Memory is off: the config is invalid and nothing from it is used. Problems:"
+
+export const REPAIR_HINT = "Run /memory-setup to repair it; it keeps every value that is still valid."
+
+export const UNREADABLE_CONFIG_NOTICE = "Memory is off: the config cannot be read. Problems:"