pi-obsidian-memory 0.0.0 → 0.1.0

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

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

@@ -0,0 +1,67 @@
+import { Value } from "typebox/value"
+
+import { checkVaultPath } from "#src/domain/vault-path"
+import { RetrievalActionSchema } from "./schemas.ts"
+import type {
+  AgentContext,
+  MemoryIdentity,
+  MemoryObservation,
+  ReadAction,
+  RetrievalInput,
+  RetrievalResult,
+} from "./types.ts"
+
+export function parseRetrievalAction(text: string, input: RetrievalInput): RetrievalResult {
+  try {
+    const action = JSON.parse(text)
+    if (!Value.Check(RetrievalActionSchema, action)) {
+      return { succeeded: false, problems: ["Invalid retrieval action"] }
+    }
+    if (action.action === "finish") {
+      if (!action.notes.every((note) => canSelectNote(note, input))) {
+        return { succeeded: false, problems: ["Selected notes require matching reads in an available vault"] }
+      }
+      return { succeeded: true, output: action }
+    }
+    const problems = checkReadAction(action, input.context)
+    if (problems.length > 0) return { succeeded: false, problems }
+    return { succeeded: true, output: action }
+  } catch {
+    return { succeeded: false, problems: ["Invalid retrieval JSON"] }
+  }
+}
+
+export function checkReadAction(action: ReadAction, context: AgentContext): string[] {
+  const problems = checkAgentVault(action.vault, context)
+  if (action.action === "get") {
+    problems.push(...checkVaultPath(action.path))
+    if (action.path.slice(-3).toLowerCase() !== ".md") problems.push("get requires a note path ending in .md")
+  }
+  if (action.action === "list") problems.push(...checkVaultPath(action.folder))
+  if (action.action === "search" && action.query.trim().length === 0) problems.push("Search query is empty")
+  return problems
+}
+
+export function checkAgentVault(vault: "global" | "project", context: AgentContext): string[] {
+  if (vault === "project" && !context.project) return ["Project vault is unavailable"]
+  return []
+}
+
+export function hasReadIdentity(identity: MemoryIdentity, observations: readonly MemoryObservation[]): boolean {
+  const latest = observations.findLast(
+    (read) => read.kind === "read" && read.vault === identity.vault && read.path === identity.path,
+  )
+  if (latest?.kind !== "read") return false
+  return latest.id === identity.id && latest.hash === identity.hash
+}
+
+function canSelectNote(identity: MemoryIdentity, input: RetrievalInput): boolean {
+  return (
+    checkAgentVault(identity.vault, input.context).length === 0 &&
+    checkVaultPath(identity.path).length === 0 &&
+    hasReadIdentity(
+      identity,
+      input.observations.filter((observation) => observation.kind !== "refused"),
+    )
+  )
+}

package/src/domain/names/constants.ts

@@ -0,0 +1,32 @@
+export const RELATIVE_NAMES = [".", ".."]
+
+export const CHARACTERS_WINDOWS_FORBIDS_IN_FILE_NAMES = ["<", ">", ":", '"', "/", "\\", "|", "?", "*"]
+
+export const CHARACTERS_THAT_BREAK_OBSIDIAN_LINKS = ["[", "]", "#", "^"]
+
+export const FIRST_PRINTABLE_CHARACTER_CODE = 32
+
+export const WINDOWS_RESERVED_NAMES = [
+  "CON",
+  "PRN",
+  "AUX",
+  "NUL",
+  "COM1",
+  "COM2",
+  "COM3",
+  "COM4",
+  "COM5",
+  "COM6",
+  "COM7",
+  "COM8",
+  "COM9",
+  "LPT1",
+  "LPT2",
+  "LPT3",
+  "LPT4",
+  "LPT5",
+  "LPT6",
+  "LPT7",
+  "LPT8",
+  "LPT9",
+]

package/src/domain/names/index.ts

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

package/src/domain/names/names.ts

@@ -0,0 +1,83 @@
+import {
+  CHARACTERS_THAT_BREAK_OBSIDIAN_LINKS,
+  CHARACTERS_WINDOWS_FORBIDS_IN_FILE_NAMES,
+  FIRST_PRINTABLE_CHARACTER_CODE,
+  RELATIVE_NAMES,
+  WINDOWS_RESERVED_NAMES,
+} from "./constants.ts"
+
+export function checkFileName(fileName: string): string[] {
+  if (fileName.length === 0) {
+    return ["file name: is empty"]
+  }
+
+  if (RELATIVE_NAMES.includes(fileName)) {
+    return [`file name: "${fileName}" is not allowed`]
+  }
+
+  const label = `file name "${fileName}"`
+  return [...checkFileSystemName(label, fileName), ...checkTrailingEdge(label, fileName)]
+}
+
+export function checkFileSystemName(label: string, name: string): string[] {
+  return [
+    ...checkForbiddenCharacters(label, name),
+    ...checkControlCharacters(label, name),
+    ...checkReservedName(label, name),
+  ]
+}
+
+export function checkLinkCharacters(label: string, name: string): string[] {
+  const breakLinks = CHARACTERS_THAT_BREAK_OBSIDIAN_LINKS.filter((character) => name.includes(character))
+  return breakLinks.map((character) => `${label}: "${character}" breaks Obsidian links`)
+}
+
+export function checkEdges(label: string, name: string): string[] {
+  if (name !== name.trim()) {
+    return [`${label}: starts or ends with a space`]
+  }
+
+  return checkTrailingDot(label, name)
+}
+
+export function checkTrailingEdge(label: string, name: string): string[] {
+  if (name !== name.trimEnd()) {
+    return [`${label}: ends with a space`]
+  }
+
+  return checkTrailingDot(label, name)
+}
+
+function checkTrailingDot(label: string, name: string): string[] {
+  if (name.endsWith(".")) {
+    return [`${label}: ends with a dot`]
+  }
+
+  return []
+}
+
+function checkForbiddenCharacters(label: string, name: string): string[] {
+  const notAllowed = CHARACTERS_WINDOWS_FORBIDS_IN_FILE_NAMES.filter((character) => name.includes(character))
+  return notAllowed.map((character) => `${label}: "${character}" is not allowed in a file name`)
+}
+
+function checkControlCharacters(label: string, name: string): string[] {
+  const hasControlCharacter = [...name].some((character) => character.charCodeAt(0) < FIRST_PRINTABLE_CHARACTER_CODE)
+  if (hasControlCharacter) {
+    return [`${label}: has a control character`]
+  }
+
+  return []
+}
+
+function checkReservedName(label: string, name: string): string[] {
+  const upperName = name.toUpperCase()
+  const isReserved = WINDOWS_RESERVED_NAMES.some(
+    (reserved) => upperName === reserved || upperName.startsWith(`${reserved}.`),
+  )
+  if (isReserved) {
+    return [`${label}: "${name}" is reserved by Windows`]
+  }
+
+  return []
+}

package/src/domain/note/check.ts

@@ -0,0 +1,68 @@
+import { Value } from "typebox/value"
+
+import { checkEdges, checkFileSystemName, checkLinkCharacters } from "#src/domain/names"
+import { FOLDER_INDEX_NAME } from "#src/domain/vault-path"
+import { NOTE_CHARACTER_SEGMENTER } from "./constants.ts"
+import { describeNoteSchemaErrors } from "./schema-errors.ts"
+import { NoteFrontmatterSchema } from "./schemas.ts"
+import type { Note, NoteFrontmatter, NoteLimits } from "./types.ts"
+
+export function checkNote(note: Note, limits: NoteLimits): string[] {
+  return [...checkFrontmatter(note.frontmatter), ...checkNoteText(note.statement, note.body, limits)]
+}
+
+export function checkNoteText(statement: string, body: string, limits: NoteLimits): string[] {
+  return [...checkStatement(statement, limits.maxStatementChars), ...checkBody(body, limits.maxBodyChars)]
+}
+
+function checkFrontmatter(frontmatter: NoteFrontmatter): string[] {
+  if (Value.Check(NoteFrontmatterSchema, frontmatter)) {
+    return []
+  }
+
+  return describeNoteSchemaErrors(Value.Errors(NoteFrontmatterSchema, frontmatter), "frontmatter")
+}
+
+function checkStatement(statement: string, maxChars: number): string[] {
+  if (statement.trim().length === 0) {
+    return ["statement: is empty"]
+  }
+
+  return [
+    ...checkLength("statement", statement, maxChars),
+    ...checkFileSystemName("statement", statement),
+    ...checkLinkCharacters("statement", statement),
+    ...checkFolderIndexName(statement),
+    ...checkEdges("statement", statement),
+  ]
+}
+
+function checkBody(body: string, maxChars: number): string[] {
+  if (body.trim().length === 0) {
+    return ["body: is empty"]
+  }
+
+  return checkLength("body", body, maxChars)
+}
+
+function checkLength(label: string, text: string, maxChars: number): string[] {
+  const length = countCharacters(text)
+  if (length > maxChars) {
+    return [`${label}: has ${length} characters, the limit is ${maxChars}`]
+  }
+
+  return []
+}
+
+function countCharacters(text: string): number {
+  const graphemes = NOTE_CHARACTER_SEGMENTER.segment(text)
+  return [...graphemes].length
+}
+
+function checkFolderIndexName(statement: string): string[] {
+  if (statement.toLowerCase() === FOLDER_INDEX_NAME) {
+    return [`statement: "${statement}" is reserved for folder indexes`]
+  }
+
+  return []
+}

package/src/domain/note/constants.ts

@@ -0,0 +1,15 @@
+import { NoteFrontmatterSchema } from "./schemas.ts"
+
+export const FRONTMATTER_FENCE = "---"
+
+export const LINE_BREAK = "\n"
+
+export const REPEATED_FIELD_ERROR_CODE = "DUPLICATE_KEY"
+
+export const KNOWN_FRONTMATTER_FIELDS = Object.keys(NoteFrontmatterSchema.properties)
+
+export const NOT_FIELDS_PROBLEM = "frontmatter: must be fields (name: value)"
+
+export const NAME_NOT_TEXT_PROBLEM = "frontmatter: a field name is not text"
+
+export const NOTE_CHARACTER_SEGMENTER = new Intl.Segmenter("en", { granularity: "grapheme" })