pi-obsidian-memory 0.0.1 → 0.1.1

package/src/domain/folder-index/listing.ts

@@ -0,0 +1,58 @@
+import { createHash } from "node:crypto"
+
+import type { VaultCatalogEntry, VaultEnumeration } from "#src/domain/vault-catalog"
+import type { FolderListingFingerprint } from "./types.ts"
+
+export function folderListingFingerprints(
+  enumeration: VaultEnumeration,
+  renderKey: string,
+): FolderListingFingerprint[] {
+  const entries = new Map(enumeration.entries.map((entry) => [entry.path, entry]))
+  return enumeration.completeDirectories.map((folder) => ({
+    folder,
+    fingerprint: fingerprintOf(enumeration, entries, folder, renderKey),
+  }))
+}
+
+function fingerprintOf(
+  enumeration: VaultEnumeration,
+  entries: Map<string, VaultCatalogEntry>,
+  folder: string,
+  renderKey: string,
+): string | null {
+  if (enumeration.failures.some((failure) => failure.path === folder || parentOf(failure.path) === folder)) {
+    return null
+  }
+
+  const children: string[] = []
+
+  for (const entry of enumeration.entries) {
+    if (parentOf(entry.path) !== folder) continue
+    if (entry.kind === "folder") children.push(JSON.stringify(["folder", nameOf(entry.path)]))
+    if (entry.kind === "note") children.push(JSON.stringify(["file", nameOf(entry.path), ...statOf(entry)]))
+  }
+
+  for (const alias of enumeration.aliases) {
+    if (parentOf(alias.path) !== folder) continue
+    const target = entries.get(alias.target)
+    if (!target || nameOf(alias.path).toLowerCase() === "index.md") return null
+    children.push(JSON.stringify(["alias", nameOf(alias.path), alias.target, ...statOf(target)]))
+  }
+
+  return createHash("sha256")
+    .update(JSON.stringify([renderKey, children.sort()]))
+    .digest("hex")
+}
+
+function parentOf(path: string): string {
+  return path.slice(0, Math.max(path.lastIndexOf("/"), 0))
+}
+
+function nameOf(path: string): string {
+  return path.slice(path.lastIndexOf("/") + 1)
+}
+
+function statOf(entry: VaultCatalogEntry): number[] {
+  const { size, mtimeMs, ctimeMs, device, inode } = entry.stat
+  return [size, mtimeMs, ctimeMs, device, inode]
+}

package/src/domain/folder-index/render.ts

@@ -0,0 +1,114 @@
+import type { Note } from "#src/domain/note"
+import { ARCHIVE_FOLDER, checkVaultPath, FOLDER_INDEX_NAME, joinVaultPath } from "#src/domain/vault-path"
+import { DONT_FORGET_LABEL, INDEX_TEXT_COLLATOR, NOTE_LINE_SEPARATOR, PROBLEM_SEPARATOR } from "./constants.ts"
+import { displayIndexName, displayIndexText } from "./display.ts"
+import type { FolderContents, InvalidNote, Titled } from "./types.ts"
+
+export function renderFolderIndex(folder: FolderContents): string {
+  const path = linkPathOf(folder)
+
+  const subjects = sortAlphabetically(folder.subjects).map((subject) => subjectLine(path, subject))
+  const notes = [...folder.notes].sort(byStatement).map((note) => noteLine(path, note))
+  const invalid = [...folder.invalid].sort(byStatement).map((note) => invalidLine(path, note))
+
+  const blocks = [
+    `# ${displayIndexText(titleOf(folder))}`,
+    ...section("Subjects", subjects),
+    ...section("Notes", notes),
+    ...section("Needs fixing", [...invalid, ...problemFolderLines(folder)]),
+    ...archiveSection(folder),
+  ]
+
+  return `${blocks.join("\n\n")}\n`
+}
+
+function titleOf(folder: FolderContents): string {
+  if (folder.kind === "root") {
+    return folder.vaultName
+  }
+
+  return folder.path
+}
+
+function linkPathOf(folder: FolderContents): string {
+  if (folder.kind === "root") {
+    return ""
+  }
+
+  return folder.path
+}
+
+function section(title: string, lines: string[]): string[] {
+  if (lines.length === 0) {
+    return []
+  }
+
+  return [`## ${title}`, lines.join("\n")]
+}
+
+function archiveSection(folder: FolderContents): string[] {
+  if (folder.kind === "root" && folder.hasArchive) {
+    return section("Archive", [subjectLine("", ARCHIVE_FOLDER)])
+  }
+
+  return []
+}
+
+function subjectLine(path: string, subject: string): string {
+  const target = joinVaultPath(path, subject, FOLDER_INDEX_NAME)
+  const problems = checkVaultPath(target)
+  if (problems.length > 0) {
+    return `- ${displayIndexName(subject)}${NOTE_LINE_SEPARATOR}${problems.map(displayIndexName).join(PROBLEM_SEPARATOR)}`
+  }
+
+  return `- [[${target}|${subject}]]`
+}
+
+function noteLine(path: string, note: Note): string {
+  const parts = [noteLink(path, note.statement), note.frontmatter.type]
+
+  if (note.frontmatter.dontForget) {
+    parts.push(DONT_FORGET_LABEL)
+  }
+
+  return `- ${parts.join(NOTE_LINE_SEPARATOR)}`
+}
+
+function invalidLine(path: string, note: InvalidNote): string {
+  const parts = [noteLink(path, note.statement), note.problems.map(displayIndexText).join(PROBLEM_SEPARATOR)]
+  return `- ${parts.join(NOTE_LINE_SEPARATOR)}`
+}
+
+function noteLink(path: string, statement: string): string {
+  const target = joinVaultPath(path, statement)
+  if (statement.length === 0 || checkVaultPath(target).length > 0) {
+    return displayIndexName(statement)
+  }
+
+  return `[[${target}|${statement}]]`
+}
+
+function problemFolderLines(folder: FolderContents): string[] {
+  if (!folder.problemFolders) {
+    return []
+  }
+
+  return [...folder.problemFolders]
+    .sort((first, second) => compareText(first.folder, second.folder))
+    .map(
+      (problem) =>
+        `- Folder ${displayIndexName(problem.folder)}${NOTE_LINE_SEPARATOR}${problem.problems.map(displayIndexText).join(PROBLEM_SEPARATOR)}`,
+    )
+}
+
+function sortAlphabetically(values: string[]): string[] {
+  return [...values].sort(compareText)
+}
+
+function byStatement(first: Titled, second: Titled): number {
+  return compareText(first.statement, second.statement)
+}
+
+function compareText(first: string, second: string): number {
+  return INDEX_TEXT_COLLATOR.compare(first, second)
+}

package/src/domain/folder-index/types.ts

@@ -0,0 +1,41 @@
+import type { Note } from "#src/domain/note"
+
+export interface Titled {
+  statement: string
+}
+
+export interface InvalidNote {
+  statement: string
+  problems: string[]
+}
+
+export interface ProblemFolder {
+  folder: string
+  problems: string[]
+}
+
+export interface SubjectFolder {
+  kind: "subject"
+  path: string
+  subjects: string[]
+  notes: Note[]
+  invalid: InvalidNote[]
+  problemFolders?: ProblemFolder[]
+}
+
+export interface RootFolder {
+  kind: "root"
+  vaultName: string
+  subjects: string[]
+  notes: Note[]
+  invalid: InvalidNote[]
+  hasArchive: boolean
+  problemFolders?: ProblemFolder[]
+}
+
+export type FolderContents = SubjectFolder | RootFolder
+
+export interface FolderListingFingerprint {
+  folder: string
+  fingerprint: string | null
+}

package/src/domain/index.ts

@@ -0,0 +1,22 @@
+export * from "./capture/index.ts"
+export * from "./command-flags/index.ts"
+export * from "./config/index.ts"
+export * from "./decision-model/index.ts"
+export * from "./embeddings/index.ts"
+export * from "./folder-index/index.ts"
+export * from "./lifecycle/index.ts"
+export * from "./loaded-memory/index.ts"
+export * from "./memory/index.ts"
+export * from "./memory-agent/index.ts"
+export * from "./names/index.ts"
+export * from "./note/index.ts"
+export * from "./path-platform/index.ts"
+export * from "./search-catalog/index.ts"
+export * from "./shell-edit/index.ts"
+export * from "./tool-flags/index.ts"
+export * from "./validation/index.ts"
+export * from "./vault-access/index.ts"
+export * from "./vault-assets/index.ts"
+export * from "./vault-catalog/index.ts"
+export * from "./vault-diagnosis/index.ts"
+export * from "./vault-path/index.ts"

package/src/domain/lifecycle/index.ts

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

package/src/domain/lifecycle/lifecycle.ts

@@ -0,0 +1,39 @@
+import type { Note } from "#src/domain/note"
+import { ARCHIVE_FOLDER, joinVaultPath } from "#src/domain/vault-path"
+import type { NoteChange, PlacedNote, Succession } from "./types.ts"
+
+export function updatedNote(note: Note, change: NoteChange, today: string): Note {
+  const { dontForget: _previous, ...kept } = note.frontmatter
+  const frontmatter = { ...kept, type: change.type, updated: today }
+  if (change.dontForget) return { ...note, frontmatter: { ...frontmatter, dontForget: true }, body: change.body }
+  return { ...note, frontmatter, body: change.body }
+}
+
+export function archiveNote(placed: PlacedNote, today: string): PlacedNote {
+  const { note } = placed
+
+  return {
+    folder: joinVaultPath(ARCHIVE_FOLDER, placed.folder),
+    note: { ...note, frontmatter: { ...note.frontmatter, archived: today } },
+  }
+}
+
+export function succeedNote(previous: PlacedNote, successor: PlacedNote, today: string): Succession {
+  const archived = archiveNote(previous, today)
+  const born = { ...successor.note.frontmatter, created: today, updated: today }
+
+  return {
+    archived: {
+      folder: archived.folder,
+      note: { ...archived.note, frontmatter: { ...archived.note.frontmatter, replacedBy: linkTo(successor) } },
+    },
+    successor: {
+      folder: successor.folder,
+      note: { ...successor.note, frontmatter: { ...born, replaces: linkTo(archived) } },
+    },
+  }
+}
+
+function linkTo(placed: PlacedNote): string {
+  return `[[${joinVaultPath(placed.folder, placed.note.statement)}]]`
+}

package/src/domain/lifecycle/types.ts

@@ -0,0 +1,17 @@
+import type { Note, NoteType } from "#src/domain/note"
+
+export interface NoteChange {
+  body: string
+  type: NoteType
+  dontForget: boolean
+}
+
+export interface PlacedNote {
+  folder: string
+  note: Note
+}
+
+export interface Succession {
+  archived: PlacedNote
+  successor: PlacedNote
+}

package/src/domain/loaded-memory/budget.ts

@@ -0,0 +1,14 @@
+import { loadedNoteBlock } from "./render.ts"
+import type { LoadedNote } from "./types.ts"
+
+export function fitBudget<Note extends LoadedNote>(notes: readonly Note[], budgetChars: number): Note[] {
+  const fitted: Note[] = []
+  let remaining = budgetChars
+  for (const note of notes) {
+    const size = loadedNoteBlock(note).length
+    if (size > remaining) return fitted
+    fitted.push(note)
+    remaining -= size
+  }
+  return fitted
+}

package/src/domain/loaded-memory/constants.ts

@@ -0,0 +1,9 @@
+export const NOTE_HEADING_PREFIX = "### "
+
+export const NOTE_FIELD_SEPARATOR = " · "
+
+export const INVALID_GONE = "the note was archived or deleted"
+
+export const INVALID_UNUSABLE = "the note is still there but cannot be used"
+
+export const INVALID_UNREADABLE = "the note cannot be read"

package/src/domain/loaded-memory/index.ts

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

package/src/domain/loaded-memory/render.ts

@@ -0,0 +1,30 @@
+import {
+  INVALID_GONE,
+  INVALID_UNREADABLE,
+  INVALID_UNUSABLE,
+  NOTE_FIELD_SEPARATOR,
+  NOTE_HEADING_PREFIX,
+} from "./constants.ts"
+import type { InvalidReason, LoadedNote } from "./types.ts"
+
+export function loadedNoteBlock(note: LoadedNote): string {
+  return `${NOTE_HEADING_PREFIX}${[note.vault, note.path, note.type].join(NOTE_FIELD_SEPARATOR)}\n${note.body}`
+}
+
+export function replacementBlock(previous: LoadedNote, current: LoadedNote): string {
+  return `This replaces the earlier copy of "${location(previous)}" loaded above; use this version and ignore the earlier one.\n\n${loadedNoteBlock(current)}`
+}
+
+export function invalidatedBlock(previous: LoadedNote, reason: InvalidReason): string {
+  return `The earlier copy of "${location(previous)}" loaded above is no longer valid: ${reasonText(reason)}. Do not rely on it.`
+}
+
+function reasonText(reason: InvalidReason): string {
+  if (reason.kind === "gone") return INVALID_GONE
+  if (reason.kind === "unusable") return `${INVALID_UNUSABLE} (${reason.problem})`
+  return `${INVALID_UNREADABLE} (${reason.problem})`
+}
+
+function location(note: LoadedNote): string {
+  return [note.vault, note.path].join(NOTE_FIELD_SEPARATOR)
+}

package/src/domain/loaded-memory/types.ts

@@ -0,0 +1,19 @@
+import type { ReadObservation } from "#src/domain/memory-agent"
+
+export type LoadedNote = Pick<ReadObservation, "vault" | "path" | "type" | "body">
+
+export interface NoteGone {
+  kind: "gone"
+}
+
+export interface NoteUnusable {
+  kind: "unusable"
+  problem: string
+}
+
+export interface NoteUnreadable {
+  kind: "unreadable"
+  problem: string
+}
+
+export type InvalidReason = NoteGone | NoteUnusable | NoteUnreadable

package/src/domain/memory/draft.ts

@@ -0,0 +1,12 @@
+import type { Note, NoteFrontmatter } from "#src/domain/note"
+import type { MemoryDraft } from "./types.ts"
+
+export function newNote(draft: MemoryDraft, id: string, day: string): Note {
+  const frontmatter: NoteFrontmatter = { id, type: draft.type, created: day, updated: day }
+
+  if (draft.dontForget) {
+    frontmatter.dontForget = true
+  }
+
+  return { statement: draft.statement, frontmatter, body: draft.body }
+}

package/src/domain/memory/index.ts

@@ -0,0 +1,4 @@
+export * from "./draft.ts"
+export * from "./schemas.ts"
+export * from "./target.ts"
+export * from "./types.ts"

package/src/domain/memory/schemas.ts

@@ -0,0 +1,15 @@
+import Type from "typebox"
+
+import { NoteTypeSchema } from "#src/domain/note"
+
+export const MemoryScopeSchema = Type.Enum(["global", "project"])
+
+export const MemoryDraftSchema = Type.Object(
+  {
+    statement: Type.String(),
+    type: NoteTypeSchema,
+    body: Type.String(),
+    dontForget: Type.Boolean(),
+  },
+  { additionalProperties: false },
+)

package/src/domain/memory/target.ts

@@ -0,0 +1,27 @@
+import { type MemoryConfig, resolveProject, vaultNameOf } from "#src/domain/config"
+import type { PathPlatform } from "#src/domain/path-platform"
+import type { MemoryScope, TargetVaultResult } from "./types.ts"
+
+export function targetVault(
+  config: MemoryConfig,
+  scope: MemoryScope,
+  workingFolder: string,
+  platform: PathPlatform,
+): TargetVaultResult {
+  if (scope === "global") {
+    const path = config.global.vault
+    return { succeeded: true, output: { path, name: vaultNameOf(path, platform) } }
+  }
+
+  const project = resolveProject(config, workingFolder, platform)
+  if (!project.succeeded) {
+    return {
+      succeeded: false,
+      reason: "no-project",
+      workingFolder,
+      problems: [`${workingFolder} has no registered project`],
+    }
+  }
+
+  return { succeeded: true, output: { path: project.output.vault, name: vaultNameOf(project.output.vault, platform) } }
+}

package/src/domain/memory/types.ts

@@ -0,0 +1,20 @@
+import type { Static } from "typebox"
+
+import type { Failed, Succeeded } from "#src/shared"
+import type { MemoryDraftSchema, MemoryScopeSchema } from "./schemas.ts"
+
+export type MemoryScope = Static<typeof MemoryScopeSchema>
+
+export type MemoryDraft = Static<typeof MemoryDraftSchema>
+
+export interface VaultTarget {
+  path: string
+  name: string
+}
+
+export interface NoProjectRefusal extends Failed {
+  reason: "no-project"
+  workingFolder: string
+}
+
+export type TargetVaultResult = Succeeded<VaultTarget> | NoProjectRefusal

package/src/domain/memory-agent/index.ts

@@ -0,0 +1,5 @@
+export * from "./input-problems.ts"
+export * from "./refusal.ts"
+export * from "./schemas.ts"
+export * from "./types.ts"
+export * from "./validate.ts"

package/src/domain/memory-agent/input-problems.ts

@@ -0,0 +1,9 @@
+import { Value } from "typebox/value"
+
+import { describeSchemaErrors } from "#src/domain/validation"
+import { RetrievalInputSchema } from "./schemas.ts"
+import type { RetrievalInput } from "./types.ts"
+
+export function retrievalInputProblems(input: RetrievalInput): string[] {
+  return describeSchemaErrors(Value.Errors(RetrievalInputSchema, input), "retrieval input")
+}

package/src/domain/memory-agent/refusal.ts

@@ -0,0 +1,6 @@
+import type { RefusedStep } from "./types.ts"
+
+export function refusalObservation(problems: string[]): RefusedStep {
+  const texts = problems.filter((problem) => problem.trim() !== "")
+  return { kind: "refused", action: "unparseable", problems: texts }
+}

package/src/domain/memory-agent/schemas.ts

@@ -0,0 +1,112 @@
+import Type from "typebox"
+
+import { NoteIdSchema, NoteTypeSchema } from "#src/domain/note"
+
+export const VaultSchema = Type.Enum(["global", "project"])
+export const PathSchema = Type.String()
+export const TextSchema = Type.String({ minLength: 1 })
+export const HashSchema = Type.String({ pattern: "^[a-f0-9]{64}$" })
+
+export const IdentitySchema = Type.Object(
+  { vault: VaultSchema, path: PathSchema, id: NoteIdSchema, hash: HashSchema },
+  { additionalProperties: false },
+)
+
+export const CandidateSchema = Type.Object(
+  { vault: VaultSchema, path: PathSchema, id: NoteIdSchema, statement: TextSchema, snippet: TextSchema },
+  { additionalProperties: false },
+)
+
+export const ListedNoteSchema = Type.Object(
+  {
+    vault: VaultSchema,
+    path: PathSchema,
+    type: NoteTypeSchema,
+    statement: TextSchema,
+    dontForget: Type.Optional(Type.Boolean()),
+  },
+  { additionalProperties: false },
+)
+
+export const ReadObservationSchema = Type.Object(
+  {
+    kind: Type.Literal("read"),
+    vault: VaultSchema,
+    path: PathSchema,
+    id: NoteIdSchema,
+    hash: HashSchema,
+    statement: TextSchema,
+    body: TextSchema,
+    type: NoteTypeSchema,
+    dontForget: Type.Boolean(),
+  },
+  { additionalProperties: false },
+)
+
+export const ObservationSchema = Type.Union([
+  ReadObservationSchema,
+  Type.Object(
+    { kind: Type.Literal("search"), query: TextSchema, candidates: Type.Array(CandidateSchema) },
+    { additionalProperties: false },
+  ),
+  Type.Object(
+    {
+      kind: Type.Literal("listing"),
+      vault: VaultSchema,
+      folder: PathSchema,
+      folders: Type.Array(PathSchema),
+      notes: Type.Array(ListedNoteSchema),
+    },
+    { additionalProperties: false },
+  ),
+  Type.Object(
+    { kind: Type.Literal("unavailable"), operation: Type.Enum(["search", "get", "list"]), detail: TextSchema },
+    { additionalProperties: false },
+  ),
+])
+
+export const RetrievalRefusedSchema = Type.Object(
+  {
+    kind: Type.Literal("refused"),
+    action: Type.Literal("unparseable"),
+    problems: Type.Array(TextSchema),
+  },
+  { additionalProperties: false },
+)
+
+export const RetrievalObservationSchema = Type.Union([ObservationSchema, RetrievalRefusedSchema])
+
+export const ReadActionSchema = Type.Union([
+  Type.Object(
+    {
+      action: Type.Literal("search"),
+      vault: VaultSchema,
+      query: TextSchema,
+    },
+    { additionalProperties: false },
+  ),
+  Type.Object({ action: Type.Literal("get"), vault: VaultSchema, path: PathSchema }, { additionalProperties: false }),
+  Type.Object(
+    { action: Type.Literal("list"), vault: VaultSchema, folder: PathSchema },
+    { additionalProperties: false },
+  ),
+])
+
+export const RetrievalActionSchema = Type.Union([
+  ReadActionSchema,
+  Type.Object({ action: Type.Literal("finish"), notes: Type.Array(IdentitySchema) }, { additionalProperties: false }),
+])
+
+export const AgentContextSchema = Type.Object(
+  { project: Type.Union([TextSchema, Type.Null()]), folder: TextSchema },
+  { additionalProperties: false },
+)
+
+export const RetrievalInputSchema = Type.Object(
+  {
+    context: AgentContextSchema,
+    query: TextSchema,
+    observations: Type.Array(RetrievalObservationSchema),
+  },
+  { additionalProperties: false },
+)

package/src/domain/memory-agent/types.ts

@@ -0,0 +1,25 @@
+import type { Static } from "typebox"
+
+import type { Failed, Succeeded } from "#src/shared"
+import type {
+  AgentContextSchema,
+  IdentitySchema,
+  ObservationSchema,
+  ReadActionSchema,
+  ReadObservationSchema,
+  RetrievalActionSchema,
+  RetrievalInputSchema,
+  RetrievalObservationSchema,
+  RetrievalRefusedSchema,
+} from "./schemas.ts"
+
+export type AgentContext = Static<typeof AgentContextSchema>
+export type MemoryIdentity = Static<typeof IdentitySchema>
+export type MemoryObservation = Static<typeof ObservationSchema>
+export type RefusedStep = Static<typeof RetrievalRefusedSchema>
+export type RetrievalObservation = Static<typeof RetrievalObservationSchema>
+export type ReadObservation = Static<typeof ReadObservationSchema>
+export type ReadAction = Static<typeof ReadActionSchema>
+export type RetrievalAction = Static<typeof RetrievalActionSchema>
+export type RetrievalInput = Static<typeof RetrievalInputSchema>
+export type RetrievalResult = Succeeded<RetrievalAction> | Failed