pi-obsidian-memory 0.0.0 → 0.1.0

package/src/pi/memory-doctor/report.ts

@@ -0,0 +1,101 @@
+import type {
+  CutoffReport,
+  CutoffValue,
+  DecisionReport,
+  DiagnosedMemory,
+  EmbeddingReport,
+  ModelReport,
+  VaultReport,
+  VaultReportFailure,
+} from "#src/usecases"
+import {
+  BLANK_HEADING,
+  COULD_NOT_CHECK,
+  CUTOFF_SOURCES,
+  CUTOFFS_HINT,
+  DOCTOR_INVALID_HEADING,
+  DOCTOR_NO_PROJECT_VAULT,
+  DOCTOR_TITLE,
+  DUPLICATES_HEADING,
+  MODELS_HEADING,
+  NO_PROBLEMS,
+  TEMPORARIES_HEADING,
+  UNREADABLE_HEADING,
+} from "./constants.ts"
+
+export function renderDoctorReport(diagnosed: DiagnosedMemory): string {
+  const sections = diagnosed.vaults.map((report) => renderVault(report, diagnosed.maxNotesPerFolder))
+  const lines = [DOCTOR_TITLE, "", ...sections.flatMap((section) => [...section, ""])]
+  if (diagnosed.projectMissing) lines.push(DOCTOR_NO_PROJECT_VAULT, "")
+  lines.push(MODELS_HEADING, ...diagnosed.models.map(renderModel), renderEmbeddings(diagnosed.embeddings))
+  lines.push(renderDecision(diagnosed.decision), renderCutoffs(diagnosed.cutoffs))
+  return lines.join("\n")
+}
+
+function renderVault(report: VaultReport | VaultReportFailure, limit: number): string[] {
+  const title = vaultTitle(report.vault)
+  if ("problems" in report) return [`${title}: ${COULD_NOT_CHECK}`, ...report.problems.map((problem) => `- ${problem}`)]
+  const { diagnosis } = report
+  const groups: string[][] = []
+  addGroup(
+    groups,
+    DOCTOR_INVALID_HEADING,
+    diagnosis.invalid.map((note) => `${note.path}: ${note.problems.join("; ")}`),
+  )
+  addGroup(
+    groups,
+    DUPLICATES_HEADING,
+    diagnosis.duplicateIds.map((copy) => `${copy.id}: ${copy.paths.join(", ")}`),
+  )
+  addGroup(groups, BLANK_HEADING, diagnosis.blank)
+  addGroup(groups, TEMPORARIES_HEADING, diagnosis.temporaries)
+  addGroup(
+    groups,
+    `Folders above ${limit} notes (consider splitting them):`,
+    diagnosis.crowdedFolders.map((folder) => `${folder.folder}: ${folder.count} notes`),
+  )
+  addGroup(groups, UNREADABLE_HEADING, report.unreadable)
+  if (groups.length === 0) return [`${title}: ${NO_PROBLEMS}`]
+  return [`${title}:`, ...groups.flat()]
+}
+
+function addGroup(groups: string[][], heading: string, items: string[]): void {
+  if (items.length === 0) return
+  groups.push([heading, ...items.map((item) => `- ${item}`)])
+}
+
+function vaultTitle(scope: string): string {
+  if (scope === "global") return "Global vault"
+  return "Project vault"
+}
+
+function renderEmbeddings(report: EmbeddingReport): string {
+  const name = `embeddings ${report.provider}/${report.model}`
+  if (report.status === "ready") return `- ${name}: ready`
+  return `- ${name}: ${report.problem}`
+}
+
+function renderDecision(report: DecisionReport): string {
+  const name = `decision model ${report.provider}/${report.model}`
+  if ("problem" in report) return `- ${name}: ${report.problem}`
+  return `- ${name}: ready (${report.detail})`
+}
+
+function cutoffText(name: string, value: CutoffValue): string {
+  const source = CUTOFF_SOURCES.get(value.source)
+  if (typeof value.value !== "number") return `${name} ${source}`
+  return `${name} ${value.value} (${source})`
+}
+
+function renderCutoffs(cutoffs: CutoffReport): string {
+  const line = `- decision cutoffs: ${cutoffText("gate", cutoffs.gate)}, ${cutoffText("relevance", cutoffs.relevance)}`
+  if (cutoffs.gate.source === "missing" || cutoffs.relevance.source === "missing") return `${line}; ${CUTOFFS_HINT}`
+  return line
+}
+
+function renderModel(report: ModelReport): string {
+  const { check } = report
+  const name = `${report.role} ${check.model.provider}/${check.model.id}`
+  if (check.status === "ok") return `- ${name}: ok`
+  return `- ${name}: ${check.problem}`
+}

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

@@ -0,0 +1,13 @@
+import type { ChatModelSource, ModelAuthResult } from "#src/pi/context"
+import type { BlankFile, VaultReport } from "#src/usecases"
+
+export interface BlankTarget {
+  vault: VaultReport["vault"]
+  blank: BlankFile
+}
+
+export interface DoctorModelPort {
+  find(provider: string, id: string): ChatModelSource | undefined
+  configured(model: ChatModelSource): boolean
+  auth(model: ChatModelSource): Promise<ModelAuthResult>
+}

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

@@ -0,0 +1,15 @@
+export const MEMORY_EXPORT_COMMAND = "memory-export"
+
+export const MEMORY_EXPORT_DESCRIPTION = "Export the global and project memory as one .zip file"
+
+export const EXPORT_FOLDER_TITLE = "Save the export in which folder? (empty: the working folder)"
+
+export const EXPORT_NAME_TITLE = "File name (empty: the suggested one)"
+
+export const EXPORT_CANCELLED = "Export cancelled: nothing was written."
+
+export const EXPORT_DONE = "Exported"
+
+export const EXPORT_SETUP_HINT = "Run /memory-setup first."
+
+export const EXPORT_NAME_TAKEN = "already exists and was kept; choose another name."

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

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

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

@@ -0,0 +1,57 @@
+import type { MemoryCommand, MemoryPaths, MemoryPiContext } from "#src/pi/context"
+import type { MemorySessionKeeper } from "#src/pi/memory-session"
+import { hostPathPlatform } from "#src/pi/paths"
+import { type ExportedMemory, exportMemory, type MemoryOperationContext } from "#src/usecases"
+import {
+  EXPORT_CANCELLED,
+  EXPORT_DONE,
+  EXPORT_FOLDER_TITLE,
+  EXPORT_NAME_TAKEN,
+  EXPORT_NAME_TITLE,
+  EXPORT_SETUP_HINT,
+  MEMORY_EXPORT_DESCRIPTION,
+} from "./constants.ts"
+import { defaultExportName } from "./name.ts"
+import type { ExportFailure } from "./types.ts"
+
+export function memoryExportCommand(paths: MemoryPaths, sessions: MemorySessionKeeper): MemoryCommand {
+  return {
+    description: MEMORY_EXPORT_DESCRIPTION,
+    async handler(_args, ctx) {
+      if (!ctx.hasUI) return
+      const { registration } = sessions.registrationFlow(ctx, paths)
+      await runMemoryExport(ctx, registration)
+    },
+  }
+}
+
+async function runMemoryExport(ctx: MemoryPiContext, context: MemoryOperationContext): Promise<void> {
+  const folder = await askOrDefault(ctx, EXPORT_FOLDER_TITLE, ctx.cwd)
+  if (typeof folder !== "string") return ctx.ui.notify(EXPORT_CANCELLED, "info")
+  const suggested = defaultExportName(new Date())
+  for (;;) {
+    const fileName = await askOrDefault(ctx, EXPORT_NAME_TITLE, suggested)
+    if (typeof fileName !== "string") return ctx.ui.notify(EXPORT_CANCELLED, "info")
+    const result = await exportMemory({ folder, fileName, platform: hostPathPlatform(process.platform) }, context)
+    if (result.succeeded) return ctx.ui.notify(describeExported(result.output), "info")
+    if (result.reason !== "exists") return ctx.ui.notify(describeRefusal(result), "error")
+    ctx.ui.notify(`${fileName} ${EXPORT_NAME_TAKEN}`, "error")
+  }
+}
+
+async function askOrDefault(ctx: MemoryPiContext, title: string, fallback: string): Promise<string | null> {
+  const answer = await ctx.ui.input(title, fallback)
+  if (typeof answer !== "string") return null
+  if (answer.trim() === "") return fallback
+  return answer.trim()
+}
+
+function describeRefusal(result: ExportFailure): string {
+  const lines = [...result.problems]
+  if (result.reason === "not-configured" || result.reason === "invalid-config") lines.push(EXPORT_SETUP_HINT)
+  return lines.join("\n")
+}
+
+function describeExported(output: ExportedMemory): string {
+  return `${EXPORT_DONE} ${output.files} files from ${output.vaults.join(" and ")} to ${output.path}`
+}

package/src/pi/memory-export/name.ts

@@ -0,0 +1,9 @@
+export function defaultExportName(now: Date): string {
+  const date = [now.getFullYear(), pad(now.getMonth() + 1), pad(now.getDate())].join("-")
+  const time = [pad(now.getHours()), pad(now.getMinutes()), pad(now.getSeconds())].join("")
+  return `memory-export-${date}-${time}.zip`
+}
+
+function pad(value: number): string {
+  return String(value).padStart(2, "0")
+}

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

@@ -0,0 +1,4 @@
+import type { Done } from "#src/shared"
+import type { ExportMemoryResult } from "#src/usecases"
+
+export type ExportFailure = Exclude<ExportMemoryResult, Done>

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

@@ -0,0 +1,12 @@
+export const MEMORY_GET_TOOL_NAME = "memory_get"
+
+export const MEMORY_GET_TOOL_LABEL = "Memory get"
+
+export const MEMORY_GET_TOOL_DESCRIPTION =
+  'Read a note in full, or a folder\'s index (path "" = root); archive/ paths can be read.'
+
+export const GET_FIELD_SEPARATOR = " · "
+
+export const GET_NEEDS_FIXING_HEADING = "Needs fixing:"
+
+export const UNCLOSED_NOTICE = "This file cannot be read as a note: it has no closed frontmatter block."

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

@@ -0,0 +1,5 @@
+export * from "./constants.ts"
+export * from "./memory-get.ts"
+export * from "./respond.ts"
+export * from "./schemas.ts"
+export * from "./types.ts"

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

@@ -0,0 +1,23 @@
+import type { MemoryPaths } from "#src/pi/context"
+import { type MemorySessionKeeper, noSessionResponse } from "#src/pi/memory-session"
+import { getMemory } from "#src/usecases"
+import { MEMORY_GET_TOOL_DESCRIPTION, MEMORY_GET_TOOL_LABEL, MEMORY_GET_TOOL_NAME } from "./constants.ts"
+import { respondToGet } from "./respond.ts"
+import { MemoryGetParamsSchema } from "./schemas.ts"
+import type { MemoryGetTool } from "./types.ts"
+
+export function memoryGetTool(paths: MemoryPaths, sessions: MemorySessionKeeper): MemoryGetTool {
+  return {
+    name: MEMORY_GET_TOOL_NAME,
+    label: MEMORY_GET_TOOL_LABEL,
+    description: MEMORY_GET_TOOL_DESCRIPTION,
+    parameters: MemoryGetParamsSchema,
+    async execute(toolCallId, params, signal, _onUpdate, ctx) {
+      const request = { vault: params.vault, path: params.path }
+      const read = { ...request, sourceCallId: toolCallId }
+      const result = await sessions.readFresh(ctx.cwd, paths, signal, (context) => getMemory(read, context))
+      if (!result) return noSessionResponse()
+      return respondToGet(request, result)
+    },
+  }
+}

package/src/pi/memory-get/respond.ts

@@ -0,0 +1,38 @@
+import { SETUP_GUIDANCE } from "#src/pi/memory-add"
+import type { GetMemoryRequest, GetMemoryResult } from "#src/usecases"
+import { GET_FIELD_SEPARATOR, GET_NEEDS_FIXING_HEADING, UNCLOSED_NOTICE } from "./constants.ts"
+import type { MemoryGetResponse } from "./types.ts"
+
+export function respondToGet(
+  request: Pick<GetMemoryRequest, "vault" | "path">,
+  result: GetMemoryResult,
+): MemoryGetResponse {
+  if (result.succeeded) {
+    if (result.output.kind === "folder") return reply([result.output.text], false)
+    const { file } = result.output
+    const problems = [
+      ...file.analysis.frontmatterProblems,
+      ...file.analysis.nameProblems,
+      ...file.analysis.bodyProblems,
+    ]
+    const lines = [[request.vault, request.path].join(GET_FIELD_SEPARATOR), file.text]
+    if (problems.length > 0) lines.push(GET_NEEDS_FIXING_HEADING, ...problems.map((problem) => `- ${problem}`))
+    return reply(lines, false)
+  }
+  switch (result.reason) {
+    case "unclosed-frontmatter":
+      return reply(
+        [UNCLOSED_NOTICE, GET_NEEDS_FIXING_HEADING, ...result.problems.map((problem) => `- ${problem}`)],
+        true,
+      )
+    case "not-configured":
+    case "invalid-config":
+      return reply([...result.problems, SETUP_GUIDANCE], true)
+    default:
+      return reply(result.problems, true)
+  }
+}
+
+function reply(lines: string[], isError: boolean): MemoryGetResponse {
+  return { content: [{ type: "text", text: lines.join("\n") }], details: undefined, isError }
+}

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

@@ -0,0 +1,13 @@
+import Type from "typebox"
+
+export const MemoryGetParamsSchema = Type.Object(
+  {
+    vault: Type.Union([Type.Literal("global"), Type.Literal("project")], {
+      description: "global: about the user. project: about this project.",
+    }),
+    path: Type.String({
+      description: 'Path inside the vault, as memory_search shows it: a note, a folder, or "" for the vault root.',
+    }),
+  },
+  { additionalProperties: false },
+)

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

@@ -0,0 +1,10 @@
+import type { AgentToolResult, ToolDefinition } from "@earendil-works/pi-coding-agent"
+import type { Static } from "typebox"
+
+import type { MemoryGetParamsSchema } from "./schemas.ts"
+
+export type MemoryGetParams = Static<typeof MemoryGetParamsSchema>
+
+export type MemoryGetTool = ToolDefinition<typeof MemoryGetParamsSchema, undefined>
+
+export type MemoryGetResponse = AgentToolResult<undefined>

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

@@ -0,0 +1,17 @@
+export const MEMORY_INIT_COMMAND = "memory-init"
+
+export const MEMORY_INIT_DESCRIPTION = "Register this folder as a project with its own memory vault"
+
+export const INIT_NAME_TITLE = "Project name (empty keeps the suggested one)"
+
+export const INIT_VAULT_TITLE = "Project vault folder (absolute path; created if missing)"
+
+export const INIT_REPOINT_VAULT_TITLE = "New vault folder for this project (absolute path; created if missing)"
+
+export const INIT_VAULT_PLACEHOLDER = "Absolute folder path"
+
+export const INIT_SETUP_HINT = "Run /memory-setup first."
+
+export const INIT_CANCELLED = "Init cancelled: nothing changed."
+
+export const INIT_DONE = "Project registered:"

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

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

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

@@ -0,0 +1,63 @@
+import type { MemoryCommand, MemoryPaths, MemoryPiContext } from "#src/pi/context"
+import type { MemorySessionKeeper } from "#src/pi/memory-session"
+import { describeRegistered, describeRegistrationFailure } from "#src/pi/registration-report"
+import {
+  checkProjectName,
+  type InitPreparation,
+  initProjectMemory,
+  prepareProjectInit,
+  type RegistrationContext,
+} from "#src/usecases"
+import {
+  INIT_CANCELLED,
+  INIT_DONE,
+  INIT_NAME_TITLE,
+  INIT_REPOINT_VAULT_TITLE,
+  INIT_SETUP_HINT,
+  INIT_VAULT_PLACEHOLDER,
+  INIT_VAULT_TITLE,
+  MEMORY_INIT_DESCRIPTION,
+} from "./constants.ts"
+
+export function memoryInitCommand(paths: MemoryPaths, sessions: MemorySessionKeeper): MemoryCommand {
+  return {
+    description: MEMORY_INIT_DESCRIPTION,
+    async handler(_args, ctx) {
+      if (!ctx.hasUI) return
+      const { registration } = sessions.registrationFlow(ctx, paths)
+      await runMemoryInit(ctx, registration)
+    },
+  }
+}
+
+async function runMemoryInit(ctx: MemoryPiContext, registration: RegistrationContext): Promise<void> {
+  const preparation = await prepareProjectInit(registration)
+  if (!preparation.succeeded) {
+    const lines = [...preparation.problems]
+    if (preparation.reason !== "unreadable") lines.push(INIT_SETUP_HINT)
+    return ctx.ui.notify(lines.join("\n"), "error")
+  }
+  const name = await askName(ctx, preparation.output)
+  if (typeof name !== "string") return ctx.ui.notify(INIT_CANCELLED, "info")
+  const vault = await askVault(ctx, preparation.output)
+  if (typeof vault !== "string") return ctx.ui.notify(INIT_CANCELLED, "info")
+  const result = await initProjectMemory({ name, vault, expectedHash: preparation.output.expectedHash }, registration)
+  if (!result.succeeded) return ctx.ui.notify(describeRegistrationFailure(result), "error")
+  ctx.ui.notify(describeRegistered(`${INIT_DONE} ${name}`, result.output), "info")
+}
+
+async function askName(ctx: MemoryPiContext, preparation: InitPreparation): Promise<string | null> {
+  if (preparation.existing) return preparation.existing.name
+  for (;;) {
+    const answer = await ctx.ui.input(INIT_NAME_TITLE, preparation.defaultName)
+    if (typeof answer !== "string") return null
+    const checked = checkProjectName(preparation, answer)
+    if (checked.succeeded) return checked.output
+    ctx.ui.notify(checked.problems.join("\n"), "error")
+  }
+}
+
+function askVault(ctx: MemoryPiContext, preparation: InitPreparation): Promise<string | undefined> {
+  if (preparation.existing) return ctx.ui.input(INIT_REPOINT_VAULT_TITLE, INIT_VAULT_PLACEHOLDER)
+  return ctx.ui.input(INIT_VAULT_TITLE, INIT_VAULT_PLACEHOLDER)
+}

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

@@ -0,0 +1,16 @@
+export const MEMORY_SEARCH_TOOL_NAME = "memory_search"
+
+export const MEMORY_SEARCH_TOOL_LABEL = "Memory search"
+
+export const MEMORY_SEARCH_TOOL_DESCRIPTION =
+  "Search long-term memory by words. Archived notes and notes without valid frontmatter are not searched."
+
+export const NO_PROJECT_VAULT = "No project vault is registered for this folder."
+
+export const READ_HINT = 'Try other words or walk folders with memory_get (path "" is the vault root).'
+
+export const SEARCH_FIELD_SEPARATOR = " · "
+
+export const DONT_FORGET_MARK = "don't forget"
+
+export const NEEDS_FIXING_MARK = "needs fixing"

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

@@ -0,0 +1,5 @@
+export * from "./constants.ts"
+export * from "./memory-search.ts"
+export * from "./respond.ts"
+export * from "./schemas.ts"
+export * from "./types.ts"

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

@@ -0,0 +1,22 @@
+import type { MemoryPaths } from "#src/pi/context"
+import { type MemorySessionKeeper, noSessionResponse } from "#src/pi/memory-session"
+import { searchMemory } from "#src/usecases"
+import { MEMORY_SEARCH_TOOL_DESCRIPTION, MEMORY_SEARCH_TOOL_LABEL, MEMORY_SEARCH_TOOL_NAME } from "./constants.ts"
+import { respondToSearch } from "./respond.ts"
+import { MemorySearchParamsSchema } from "./schemas.ts"
+import type { MemorySearchTool } from "./types.ts"
+
+export function memorySearchTool(paths: MemoryPaths, sessions: MemorySessionKeeper): MemorySearchTool {
+  return {
+    name: MEMORY_SEARCH_TOOL_NAME,
+    label: MEMORY_SEARCH_TOOL_LABEL,
+    description: MEMORY_SEARCH_TOOL_DESCRIPTION,
+    parameters: MemorySearchParamsSchema,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const request = { query: params.query, vault: params.vault }
+      const result = await sessions.readFresh(ctx.cwd, paths, signal, (context) => searchMemory(request, context))
+      if (!result) return noSessionResponse()
+      return respondToSearch(result)
+    },
+  }
+}

package/src/pi/memory-search/respond.ts

@@ -0,0 +1,62 @@
+import { SETUP_GUIDANCE } from "#src/pi/memory-add"
+import type { SearchedMemory, SearchMemoryResult, VaultSearchFailure, VaultSearchHits } from "#src/usecases"
+import {
+  DONT_FORGET_MARK,
+  NEEDS_FIXING_MARK,
+  NO_PROJECT_VAULT,
+  READ_HINT,
+  SEARCH_FIELD_SEPARATOR,
+} from "./constants.ts"
+import type { MemorySearchResponse } from "./types.ts"
+
+export function respondToSearch(result: SearchMemoryResult): MemorySearchResponse {
+  if (result.succeeded) return describeSearched(result.output)
+  switch (result.reason) {
+    case "not-configured":
+    case "invalid-config":
+      return reply([...result.problems, SETUP_GUIDANCE], true)
+    default:
+      return reply(result.problems, true)
+  }
+}
+
+function describeSearched(searched: SearchedMemory): MemorySearchResponse {
+  const lines: string[] = []
+  const failures = searched.vaults.filter(isFailure)
+  const answered = searched.vaults.filter(isHits)
+  for (const entry of answered) {
+    for (const hit of entry.hits) lines.push(describeHit(entry.vault, hit))
+  }
+  if (answered.length > 0 && lines.length === 0) {
+    const names = answered.map((entry) => entry.vault).join(", ")
+    lines.push(`No notes found in ${names}. ${READ_HINT}`)
+  }
+  for (const entry of failures) {
+    for (const problem of entry.problems) lines.push(`Could not search ${entry.vault}: ${problem}`)
+  }
+  for (const entry of answered) {
+    for (const warning of entry.warnings) lines.push(`Warning: ${warning}`)
+  }
+  lines.push(...searched.semantic.problems)
+  if (searched.projectMissing) lines.push(NO_PROJECT_VAULT)
+  return reply(lines, answered.length === 0)
+}
+
+function describeHit(vault: string, hit: VaultSearchHits["hits"][number]): string {
+  const fields = [vault, hit.path, hit.type]
+  if (hit.dontForget) fields.push(DONT_FORGET_MARK)
+  if (hit.needsFixing) fields.push(NEEDS_FIXING_MARK)
+  return fields.join(SEARCH_FIELD_SEPARATOR)
+}
+
+function isFailure(entry: VaultSearchHits | VaultSearchFailure): entry is VaultSearchFailure {
+  return "problems" in entry
+}
+
+function isHits(entry: VaultSearchHits | VaultSearchFailure): entry is VaultSearchHits {
+  return "hits" in entry
+}
+
+function reply(lines: string[], isError: boolean): MemorySearchResponse {
+  return { content: [{ type: "text", text: lines.join("\n") }], details: undefined, isError }
+}

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

@@ -0,0 +1,11 @@
+import Type from "typebox"
+
+export const MemorySearchParamsSchema = Type.Object(
+  {
+    query: Type.String({ minLength: 1, description: "Words to look for, in English." }),
+    vault: Type.Union([Type.Literal("global"), Type.Literal("project"), Type.Literal("both")], {
+      description: "global: about the user. project: about this project. both: search the two, each on its own.",
+    }),
+  },
+  { additionalProperties: false },
+)

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

@@ -0,0 +1,10 @@
+import type { AgentToolResult, ToolDefinition } from "@earendil-works/pi-coding-agent"
+import type { Static } from "typebox"
+
+import type { MemorySearchParamsSchema } from "./schemas.ts"
+
+export type MemorySearchParams = Static<typeof MemorySearchParamsSchema>
+
+export type MemorySearchTool = ToolDefinition<typeof MemorySearchParamsSchema, undefined>
+
+export type MemorySearchResponse = AgentToolResult<undefined>

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

@@ -0,0 +1,7 @@
+export const NO_SESSION_NOTICE = "Memory is not ready in this session; try again after the session has started."
+
+export const STALE_SESSION_REASON = "stale-session"
+
+export const CAPTURE_BRANCH = "capture"
+
+export const RETRIEVAL_BRANCH = "retrieval"

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

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

package/src/pi/memory-session/keeper.ts

@@ -0,0 +1,101 @@
+import type { MemoryPaths, MemoryPiContext } from "#src/pi/context"
+import { hostPathPlatform } from "#src/pi/paths"
+import type { SemanticRuntime } from "#src/pi/semantic"
+import { createMemorySession, LoadedMemory, type MemoryOperationContext, type MemorySession } from "#src/usecases"
+import { CAPTURE_BRANCH, RETRIEVAL_BRANCH, STALE_SESSION_REASON } from "./constants.ts"
+import type { ReadOutcome, ReadRun, RegistrationFlow } from "./types.ts"
+
+export class MemorySessionKeeper {
+  #session: MemorySession | null = null
+  #semantic: SemanticRuntime | null = null
+  #loaded = new LoadedMemory()
+
+  constructor(semantic?: SemanticRuntime) {
+    if (semantic) this.#semantic = semantic
+  }
+
+  start(ctx: MemoryPiContext): MemorySession {
+    if (this.#session) this.#session.abortPending()
+    const session = createMemorySession({ sessionId: ctx.sessionManager.getSessionId(), branchId: null })
+    if (this.#semantic) this.#semantic.attach(ctx)
+    this.#session = session
+    this.#loaded = new LoadedMemory()
+    return session
+  }
+
+  shutdown(): void {
+    if (this.#session) this.#session.abortPending()
+    this.#session = null
+  }
+
+  operationContext(
+    session: MemorySession,
+    workingFolder: string,
+    paths: MemoryPaths,
+    callerSignal: AbortSignal | undefined,
+  ): MemoryOperationContext {
+    const stamp = session.stamp()
+    let signal = session.signal(stamp)
+    if (callerSignal) signal = AbortSignal.any([signal, callerSignal])
+    const context: MemoryOperationContext = {
+      configPath: paths.configPath,
+      indexPath: paths.indexPath,
+      workingFolder,
+      platform: hostPathPlatform(process.platform),
+      session,
+      stamp,
+      signal,
+    }
+    if (this.#semantic) context.semantic = this.#semantic.source
+    return context
+  }
+
+  currentOperation(
+    workingFolder: string,
+    paths: MemoryPaths,
+    callerSignal: AbortSignal | undefined,
+  ): MemoryOperationContext | null {
+    if (!this.#session) return null
+    return this.operationContext(this.#session, workingFolder, paths, callerSignal)
+  }
+
+  loaded(): LoadedMemory {
+    return this.#loaded
+  }
+
+  captureOperation(workingFolder: string, paths: MemoryPaths): MemoryOperationContext | null {
+    return this.#siblingOperation(CAPTURE_BRANCH, workingFolder, paths)
+  }
+
+  retrievalOperation(workingFolder: string, paths: MemoryPaths): MemoryOperationContext | null {
+    return this.#siblingOperation(RETRIEVAL_BRANCH, workingFolder, paths)
+  }
+
+  #siblingOperation(branchId: string, workingFolder: string, paths: MemoryPaths): MemoryOperationContext | null {
+    const main = this.#session
+    if (!main) return null
+    const sibling = main.sibling({ sessionId: main.stamp().sessionId, branchId })
+    return this.operationContext(sibling, workingFolder, paths, main.signal(main.stamp()))
+  }
+
+  async readFresh<Outcome extends ReadOutcome>(
+    workingFolder: string,
+    paths: MemoryPaths,
+    callerSignal: AbortSignal | undefined,
+    run: ReadRun<Outcome>,
+  ): Promise<Outcome | null> {
+    const first = this.currentOperation(workingFolder, paths, callerSignal)
+    if (!first) return null
+    const result = await run(first)
+    if (result.succeeded || result.reason !== STALE_SESSION_REASON) return result
+    const second = this.currentOperation(workingFolder, paths, callerSignal)
+    if (!second) return result
+    return run(second)
+  }
+
+  registrationFlow(ctx: MemoryPiContext, paths: MemoryPaths): RegistrationFlow {
+    let session = this.#session
+    if (!session) session = this.start(ctx)
+    return { session, registration: this.operationContext(session, ctx.cwd, paths, undefined) }
+  }
+}