pi-obsidian-memory 0.0.1 → 0.1.0

package/src/usecases/check-vault-access/targets.ts

@@ -0,0 +1,49 @@
+import {
+  absoluteCandidate,
+  canonicalizeAccessPath,
+  fileIdentity,
+  type PathIdentity,
+  pathIdentities,
+  vaultAccessRefusal,
+} from "#src/services"
+import { NAMESPACE_PATH_START, NO_FILE_ID } from "./constants.ts"
+import type { GuardedTargets, TargetCheck } from "./types.ts"
+
+export async function guardedTargets(written: string[]): Promise<GuardedTargets> {
+  const roots = [...written]
+  const identities: PathIdentity[] = []
+  for (const path of written) {
+    const canonical = await canonicalizeAccessPath(path)
+    if (canonical.succeeded) roots.push(canonical.output)
+    const identity = await fileIdentity(path)
+    if (identity.succeeded && hasFileId(identity.output)) identities.push(identity.output)
+  }
+  return { roots, identities }
+}
+
+export async function hitsTargets(check: TargetCheck): Promise<boolean> {
+  const { request, cwd, home, platform, targets } = check
+  if (vaultAccessRefusal(request, cwd, home, targets.roots, platform)) return true
+  if (request.kind === "command") return false
+  const absolute = absoluteCandidate(request.path, cwd, home, platform)
+  const canonical = await canonicalizeAccessPath(absolute)
+  if (
+    canonical.succeeded &&
+    vaultAccessRefusal({ kind: request.kind, path: canonical.output }, cwd, home, targets.roots, platform)
+  ) {
+    return true
+  }
+  return sharesIdentity(absolute, targets.identities)
+}
+
+async function sharesIdentity(absolute: string, identities: PathIdentity[]): Promise<boolean> {
+  const found = await pathIdentities(absolute)
+  if (!found.succeeded) return NAMESPACE_PATH_START.test(absolute)
+  return found.output
+    .filter(hasFileId)
+    .some((seen) => identities.some((target) => target.device === seen.device && target.inode === seen.inode))
+}
+
+function hasFileId(identity: PathIdentity): boolean {
+  return identity.inode !== NO_FILE_ID
+}

package/src/usecases/check-vault-access/types.ts

@@ -0,0 +1,33 @@
+export type { VaultAccessRequest } from "#src/services"
+
+import type { PathIdentity, PathPlatform, VaultAccessRequest } from "#src/services"
+import type { Done, Failed } from "#src/shared"
+
+export type { PathPlatform } from "#src/services"
+
+export interface CheckVaultAccessInput {
+  configPath: string
+  cwd: string
+  home: string
+  platform: PathPlatform
+  request: VaultAccessRequest
+}
+
+export interface VaultAccessRefusal extends Failed {
+  reason: "vault-access"
+}
+
+export type CheckVaultAccessResult = Done | VaultAccessRefusal
+
+export interface GuardedTargets {
+  roots: string[]
+  identities: PathIdentity[]
+}
+
+export interface TargetCheck {
+  request: VaultAccessRequest
+  cwd: string
+  home: string
+  platform: PathPlatform
+  targets: GuardedTargets
+}

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

@@ -0,0 +1,48 @@
+import { completeBlankFile, type Note, newNoteId, refreshIndexes, today } from "#src/services"
+import { refreshWarnings, warningsOf } from "#src/usecases/memory-change"
+import {
+  captureMemoryOperationContext,
+  type MemoryOperationContext,
+  memoryAdmissionRefusal,
+} from "#src/usecases/operation-context"
+import { resolveLeasedMemory, selectMemoryVault } from "#src/usecases/resolve-memory/leased"
+import type { CompleteBlankMemoryRequest, CompleteBlankMemoryResult } from "./types.ts"
+
+export async function completeBlankMemory(
+  request: CompleteBlankMemoryRequest,
+  callerContext: MemoryOperationContext,
+): Promise<CompleteBlankMemoryResult> {
+  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 target = selectMemoryVault(memory.output, request.vault)
+    if (!target.succeeded) return target
+    const day = today()
+    const note: Note = {
+      statement: statementOf(request.path),
+      frontmatter: { id: newNoteId(), type: request.type, created: day, updated: day },
+      body: request.body,
+    }
+    const completed = await completeBlankFile(target.output.vault, {
+      path: request.path,
+      expectedHash: request.expectedHash,
+      note,
+      confirmed: true,
+    })
+    if (!completed.succeeded) return completed
+    const folder = request.path.slice(0, Math.max(0, request.path.lastIndexOf("/")))
+    const refreshed = await refreshIndexes(target.output.vault, folder)
+    const maintenanceProblems = [...warningsOf(completed), ...refreshWarnings(refreshed)]
+    return { succeeded: true, output: { vault: request.vault, path: request.path, maintenanceProblems } }
+  } finally {
+    lease.release()
+  }
+}
+
+function statementOf(path: string): string {
+  const name = path.slice(path.lastIndexOf("/") + 1)
+  return name.slice(0, -".md".length)
+}

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

@@ -0,0 +1,3 @@
+import { CompleteBlankMemoryRequestSchema } from "./schemas.ts"
+
+export const BLANK_NOTE_TYPES = CompleteBlankMemoryRequestSchema.properties.type.enum

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

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

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

@@ -0,0 +1,14 @@
+import Type from "typebox"
+
+import { MemoryDraftSchema, MemoryScopeSchema } from "#src/services"
+
+export const CompleteBlankMemoryRequestSchema = Type.Object(
+  {
+    vault: MemoryScopeSchema,
+    path: Type.String(),
+    expectedHash: Type.String(),
+    type: MemoryDraftSchema.properties.type,
+    body: MemoryDraftSchema.properties.body,
+  },
+  { additionalProperties: false },
+)

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[]
+}