@chendpoc/pi-memory 0.1.13 → 0.2.0

package/src/store/backend.ts

@@ -0,0 +1,66 @@
+import lockfile from "proper-lockfile";
+
+import {
+  MEMORY_LOCK_MAX_TIMEOUT_MS,
+  MEMORY_LOCK_MIN_TIMEOUT_MS,
+  MEMORY_LOCK_RETRIES,
+} from "../constants/timing.js";
+import {
+  ensureDir,
+  ensureFile,
+  joinPath,
+  listDir,
+  pathDirname,
+  readText,
+  removeFile,
+  writeText,
+} from "../utils/fs.js";
+
+import { isAutoOverflowFile } from "./paths.js";
+
+export class MarkdownMemoryBackend {
+  constructor(private readonly memoryFile: string) {}
+
+  async ensureAgentDir(): Promise<void> {
+    await ensureDir(pathDirname(this.memoryFile));
+  }
+
+  async readText(path: string): Promise<string> {
+    return readText(path);
+  }
+
+  async writeText(path: string, content: string): Promise<void> {
+    await writeText(path, content);
+  }
+
+  async listAutoFiles(agentDir: string): Promise<string[]> {
+    const names = await listDir(agentDir);
+    return names.filter(isAutoOverflowFile).sort();
+  }
+
+  autoFilePath(agentDir: string, fileName: string): string {
+    return joinPath(agentDir, fileName);
+  }
+
+  async deleteAutoFile(path: string): Promise<void> {
+    await removeFile(path);
+  }
+
+  async withMemoryLock<T>(fn: () => Promise<T>): Promise<T> {
+    await this.ensureAgentDir();
+    await ensureFile(this.memoryFile);
+
+    const release = await lockfile.lock(this.memoryFile, {
+      retries: {
+        retries: MEMORY_LOCK_RETRIES,
+        minTimeout: MEMORY_LOCK_MIN_TIMEOUT_MS,
+        maxTimeout: MEMORY_LOCK_MAX_TIMEOUT_MS,
+      },
+    });
+    try {
+      return await fn();
+    } finally {
+      await release();
+    }
+  }
+}

package/src/store/index.ts

@@ -0,0 +1,5 @@
+export { MemoryStore, createMemoryStore } from "./memoryStore.js";
+export { MarkdownMemoryBackend } from "./backend.js";
+export { getAgentPaths, resolveAgentDir } from "./paths.js";
+export * from "./types.js";
+export * from "../constants/memory.js";

package/src/store/indexChunks.ts

@@ -0,0 +1,89 @@
+import type { IndexDocument } from "../sidecar/protocol.js";
+import type { ChunkingConfig } from "../config/chunking.js";
+import { CHUNKING_DISABLED_MAX_CHARS } from "../constants/chunking.js";
+import { pathBasename } from "../utils/fs.js";
+import type { MemorySection, ParsedEntry } from "./types.js";
+
+function formatChunkContent(section: MemorySection, body: string): string {
+  return `[${section}] ${body.trim()}`;
+}
+
+/**
+ * Split long text on paragraph / line / sentence boundaries, then hard-wrap at maxChars.
+ */
+export function splitTextByMaxChars(text: string, maxChars: number): string[] {
+  const trimmed = text.trim();
+  if (!trimmed) return [];
+  if (maxChars <= 0 || trimmed.length <= maxChars) return [trimmed];
+
+  const parts: string[] = [];
+  let remaining = trimmed;
+
+  while (remaining.length > maxChars) {
+    let cut = maxChars;
+    const minCut = Math.floor(maxChars * 0.35);
+
+    const paragraph = remaining.lastIndexOf("\n\n", cut);
+    if (paragraph >= minCut) {
+      cut = paragraph;
+    } else {
+      const line = remaining.lastIndexOf("\n", cut);
+      if (line >= minCut) {
+        cut = line;
+      } else {
+        const sentence = remaining.lastIndexOf(". ", cut);
+        if (sentence >= minCut) {
+          cut = sentence + 1;
+        } else {
+          const space = remaining.lastIndexOf(" ", cut);
+          if (space >= minCut) {
+            cut = space;
+          }
+        }
+      }
+    }
+
+    const part = remaining.slice(0, cut).trim();
+    if (part) parts.push(part);
+    remaining = remaining.slice(cut).trim();
+    if (!part && remaining.length > 0) {
+      parts.push(remaining.slice(0, maxChars).trim());
+      remaining = remaining.slice(maxChars).trim();
+    }
+  }
+
+  if (remaining) parts.push(remaining);
+  return parts.length > 0 ? parts : [trimmed];
+}
+
+export function buildIndexDocuments(
+  entries: ParsedEntry[],
+  chunking: ChunkingConfig,
+): IndexDocument[] {
+  const docs: IndexDocument[] = [];
+  const maxChars =
+    chunking.maxChars <= CHUNKING_DISABLED_MAX_CHARS
+      ? CHUNKING_DISABLED_MAX_CHARS
+      : chunking.maxChars;
+
+  for (const entry of entries) {
+    const bodies =
+      maxChars <= CHUNKING_DISABLED_MAX_CHARS
+        ? [entry.content.trim()].filter(Boolean)
+        : splitTextByMaxChars(entry.content, maxChars);
+
+    if (bodies.length === 0) continue;
+
+    bodies.forEach((body, index) => {
+      const id = bodies.length === 1 ? entry.id : `${entry.id}#${index}`;
+      docs.push({
+        id,
+        content: formatChunkContent(entry.section, body),
+        source: pathBasename(entry.sourceFile),
+        timestamp: entry.timestamp,
+      });
+    });
+  }
+
+  return docs;
+}

package/src/store/markdown/format.ts

@@ -0,0 +1,16 @@
+import type { MemorySection, StoreMemoryEntry } from "../types.js";
+
+export function formatEntryLine(entry: StoreMemoryEntry): string {
+  const prefix = entry.userAuthored ? "[user] " : "";
+  const meta = `<!-- id:${entry.id}${entry.userAuthored ? " user" : ""} ts:${entry.timestamp} -->`;
+  return `- ${prefix}${entry.content.trim()} ${meta}`;
+}
+
+export function formatSectionHeader(section: MemorySection): string {
+  return `## ${section}`;
+}
+
+export function countLines(content: string): number {
+  if (!content) return 0;
+  return content.split("\n").length;
+}

package/src/store/markdown/parse.ts

@@ -0,0 +1,63 @@
+import { pathBasename } from "../../utils/fs.js";
+import { epochTimestamp } from "../../utils/time.js";
+
+import { OVERFLOW_POINTER_RE } from "../../constants/memory.js";
+import { MEMORY_SECTIONS, type MemorySection, type ParsedEntry } from "../types.js";
+
+const SECTION_RE = /^##\s+(Preferences|Conventions|Findings|Todos)\s*$/;
+const ENTRY_META_RE = /<!--\s*id:([^\s]+)(?:\s+user)?(?:\s+ts:([^\s]+))?\s*-->/;
+const USER_PREFIX_RE = /^\[user\]\s+/;
+
+export function parseMemoryMarkdown(content: string, sourceFile: string): ParsedEntry[] {
+  const entries: ParsedEntry[] = [];
+  let section: MemorySection | undefined;
+  const lines = content.split("\n");
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    const sectionMatch = line.match(SECTION_RE);
+    if (sectionMatch) {
+      section = sectionMatch[1] as MemorySection;
+      continue;
+    }
+
+    if (!line.startsWith("- ") || !section) continue;
+
+    const pointerMatch = line.match(OVERFLOW_POINTER_RE);
+    if (pointerMatch) continue;
+
+    const metaMatch = line.match(ENTRY_META_RE);
+    const id = metaMatch?.[1] ?? `${pathBasename(sourceFile)}:${i + 1}`;
+    const timestamp = metaMatch?.[2] ?? epochTimestamp();
+    let body = line.slice(2).replace(ENTRY_META_RE, "").trim();
+    const userAuthored = USER_PREFIX_RE.test(body);
+    if (userAuthored) body = body.replace(USER_PREFIX_RE, "").trim();
+
+    if (!body) continue;
+
+    entries.push({
+      id,
+      section,
+      content: body,
+      userAuthored: userAuthored || undefined,
+      timestamp,
+      sourceFile,
+      line: i + 1,
+    });
+  }
+
+  return entries;
+}
+
+export function listOverflowPointers(content: string): string[] {
+  const files: string[] = [];
+  for (const line of content.split("\n")) {
+    const match = line.match(OVERFLOW_POINTER_RE);
+    if (match?.[1]) files.push(match[1]);
+  }
+  return files;
+}
+
+export function isKnownSection(name: string): name is MemorySection {
+  return (MEMORY_SECTIONS as readonly string[]).includes(name);
+}

package/src/store/markdown/template.ts

@@ -0,0 +1,24 @@
+import { MEMORY_SECTIONS } from "../types.js";
+
+const SECTION_HINTS: Record<(typeof MEMORY_SECTIONS)[number], string> = {
+  Preferences: "User preferences and defaults.",
+  Conventions: "Project or workflow conventions.",
+  Findings: "Durable conclusions, decisions, and facts.",
+  Todos: "Items to carry forward across sessions.",
+};
+
+/** Canonical empty MEMORY.md scaffold (ground truth format). */
+export function defaultMemoryTemplate(): string {
+  const sections = MEMORY_SECTIONS.map((section) => {
+    return `## ${section}\n\n<!-- ${SECTION_HINTS[section]} -->\n`;
+  }).join("\n");
+
+  return `# Memory
+
+<!-- pi-memory ground truth — cross-session durable notes for the Pi agent.
+     Sections: Preferences | Conventions | Findings | Todos
+     User entries: /remember → - [user] text <!-- id:... user ts:... -->
+     Line cap: 150; overflow spills to auto-*.md in this directory. -->
+
+${sections}`;
+}