@loreai/core 0.0.1 → 0.10.0

package/dist/types/types.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Host-agnostic message and part types for Lore's core memory engine.
+ *
+ * These replace the direct dependency on `@opencode-ai/sdk`'s `Message` and
+ * `Part` types so the core can run under any host (OpenCode, Pi, future ACP
+ * server, etc.). Each host adapter converts between its native types and these
+ * Lore-internal types at the hook boundary.
+ *
+ * The type surface is intentionally minimal — only the fields that Lore's
+ * runtime code actually reads/writes are included. Fields that only exist for
+ * the host's UI or for features Lore doesn't touch are omitted.
+ */
+export type LoreUserMessage = {
+    id: string;
+    sessionID: string;
+    role: "user";
+    time: {
+        created: number;
+    };
+    /** Agent name (e.g. "build", "plan"). Host-specific; stored as metadata. */
+    agent: string;
+    /** Model used for this turn. Stored as metadata. */
+    model: {
+        providerID: string;
+        modelID: string;
+    };
+};
+export type LoreAssistantMessage = {
+    id: string;
+    sessionID: string;
+    role: "assistant";
+    time: {
+        created: number;
+    };
+    parentID: string;
+    modelID: string;
+    providerID: string;
+    mode: string;
+    path: {
+        cwd: string;
+        root: string;
+    };
+    cost: number;
+    tokens: {
+        input: number;
+        output: number;
+        reasoning: number;
+        cache: {
+            read: number;
+            write: number;
+        };
+    };
+};
+/** Discriminated union on `.role`. */
+export type LoreMessage = LoreUserMessage | LoreAssistantMessage;
+export type LoreTextPart = {
+    id: string;
+    sessionID: string;
+    messageID: string;
+    type: "text";
+    text: string;
+    /** Marks Lore-injected synthetic messages (e.g. distilled prefix). */
+    synthetic?: boolean;
+    /** Optional timing info — present on real messages, faked on synthetics. */
+    time?: {
+        start: number;
+        end?: number;
+    };
+};
+export type LoreReasoningPart = {
+    id: string;
+    sessionID: string;
+    messageID: string;
+    type: "reasoning";
+    text: string;
+};
+export type LoreToolStatePending = {
+    status: "pending";
+    input: unknown;
+};
+export type LoreToolStateRunning = {
+    status: "running";
+    input: unknown;
+    metadata?: unknown;
+    time: {
+        start: number;
+    };
+};
+export type LoreToolStateCompleted = {
+    status: "completed";
+    input: unknown;
+    output: string;
+    metadata?: unknown;
+    time: {
+        start: number;
+        end: number;
+    };
+};
+export type LoreToolStateError = {
+    status: "error";
+    input: unknown;
+    error: string;
+    metadata?: unknown;
+    time: {
+        start: number;
+        end: number;
+    };
+};
+export type LoreToolState = LoreToolStatePending | LoreToolStateRunning | LoreToolStateCompleted | LoreToolStateError;
+export type LoreToolPart = {
+    id: string;
+    sessionID: string;
+    messageID: string;
+    type: "tool";
+    tool: string;
+    callID: string;
+    state: LoreToolState;
+};
+/**
+ * Discriminated union on `.type`.
+ *
+ * Only `text`, `reasoning`, and `tool` are processed by Lore's core logic.
+ * All other part types (step-start, snapshot, patch, agent, retry, etc.) flow
+ * through untouched — they hit the `else` branch with a flat 20-token estimate
+ * in `estimateParts()` and are preserved as-is in the message transform.
+ *
+ * For type-safe narrowing, use `isToolPart()` / `isTextPart()` helpers below.
+ */
+export type LorePart = LoreTextPart | LoreReasoningPart | LoreToolPart | LoreGenericPart;
+/**
+ * Passthrough for host-specific part types that Lore doesn't process.
+ * The `type` field is typed as `string` since Lore only cares that it's not
+ * one of the three known types.
+ */
+export type LoreGenericPart = {
+    type: string;
+    [key: string]: unknown;
+};
+export declare function isTextPart(p: LorePart): p is LoreTextPart;
+export declare function isReasoningPart(p: LorePart): p is LoreReasoningPart;
+export declare function isToolPart(p: LorePart): p is LoreToolPart;
+export type LoreMessageWithParts = {
+    info: LoreMessage;
+    parts: LorePart[];
+};
+/**
+ * Abstract interface for single-turn LLM prompt→response.
+ *
+ * All of Lore's background LLM work (distillation, curation, query expansion)
+ * is single-turn: one system+user message in, one text response out. No tool
+ * calling, no multi-turn. This interface captures that minimal surface.
+ *
+ * Host adapters implement this:
+ * - OpenCode: wraps `client.session.create()` + `client.session.prompt()`
+ * - Pi: wraps `complete()` from `@mariozechner/pi-ai`
+ * - Standalone: direct `fetch()` to provider APIs
+ */
+export interface LLMClient {
+    /**
+     * Send a single prompt and return the text response.
+     *
+     * @param system  System prompt text
+     * @param user    User message text
+     * @param opts    Optional model selection and worker identification
+     * @returns The assistant's text response, or null on failure
+     */
+    prompt(system: string, user: string, opts?: {
+        /** Override model for this call. */
+        model?: {
+            providerID: string;
+            modelID: string;
+        };
+        /**
+         * Opaque worker identifier used by the host to route the request
+         * (e.g. OpenCode uses this as the session agent name).
+         */
+        workerID?: string;
+    }): Promise<string | null>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types/worker.d.ts

@@ -0,0 +1,6 @@
+export type { LLMClient } from "./types";
+/** Set of ALL worker session IDs across distillation, curator, and query expansion.
+ *  Used by shouldSkip() in host adapters to avoid storing/distilling worker messages. */
+export declare const workerSessionIDs: Set<string>;
+export declare function isWorkerSession(sessionID: string): boolean;
+//# sourceMappingURL=worker.d.ts.map

package/dist/types/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/worker.ts"],"names":[],"mappings":"AAaA,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAMzC;yFACyF;AACzF,eAAO,MAAM,gBAAgB,aAAoB,CAAC;AAElD,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE1D"}

package/package.json

@@ -1,16 +1,59 @@
 {
   "name": "@loreai/core",
-  "version": "0.0.1",
-  "description": "Placeholder — real release follows via CI. See https://github.com/BYK/loreai",
+  "version": "0.10.0",
+  "type": "module",
   "license": "MIT",
-  "author": "BYK",
+  "description": "Shared memory engine for Lore — three-tier storage, distillation, gradient context management",
+  "main": "./dist/node/index.js",
+  "types": "./dist/node/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "default": "./dist/node/index.js"
+    }
+  },
+  "imports": {
+    "#db/driver": {
+      "bun": "./src/db/driver.bun.ts",
+      "default": "./src/db/driver.node.ts"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "bun run script/build.ts"
+  },
+  "dependencies": {
+    "remark": "^15.0.1",
+    "uuidv7": "^1.1.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/mdast": "^4.0.4"
+  },
+  "files": [
+    "src/",
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.5"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/BYK/loreai.git",
     "directory": "packages/core"
   },
-  "homepage": "https://github.com/BYK/loreai",
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "keywords": [
+    "lore",
+    "memory",
+    "llm",
+    "sqlite",
+    "fts5",
+    "distillation"
+  ],
+  "author": "BYK"
 }

package/src/agents-file.ts

@@ -0,0 +1,406 @@
+/**
+ * agents-file.ts — AGENTS.md export/import/sync for lore.
+ *
+ * Lore owns a clearly delimited section inside the file, bounded by HTML
+ * comment markers. Everything outside those markers is preserved verbatim.
+ * Each knowledge entry is preceded by a hidden <!-- lore:UUID --> comment so
+ * the same entry can be tracked across machines and merge conflicts resolved
+ * without duplication.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { dirname } from "path";
+import * as ltm from "./ltm";
+import { serialize, inline, h, ul, liph, strong, t, root, unescapeMarkdown } from "./markdown";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+export const LORE_SECTION_START =
+  "<!-- This section is maintained by the coding agent via lore (https://github.com/BYK/loreai) -->";
+export const LORE_SECTION_END = "<!-- End lore-managed section -->";
+
+/**
+ * All known start-marker variants, ordered newest-first.
+ * When we renamed the marker in the past, old files kept the old text.
+ * splitFile() matches any of these so it can strip all lore sections
+ * regardless of which marker version was used to write them.
+ */
+const ALL_START_MARKERS = [
+  LORE_SECTION_START,
+  // Pre-rename URL (BYK/opencode-lore → BYK/loreai).
+  "<!-- This section is maintained by the coding agent via lore (https://github.com/BYK/opencode-lore) -->",
+  "<!-- This section is auto-maintained by lore (https://github.com/BYK/opencode-lore) -->",
+] as const;
+
+/** Regex matching a valid UUID (v4 or v7) — 8-4-4-4-12 hex groups. */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+/** Matches `<!-- lore:UUID -->` tracking markers. */
+const MARKER_RE = /^<!--\s*lore:([0-9a-f-]+)\s*-->$/;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type ParsedFileEntry = {
+  /** UUID from `<!-- lore:UUID -->` marker, or null for hand-written entries. */
+  id: string | null;
+  category: string;
+  title: string;
+  content: string;
+};
+
+// ---------------------------------------------------------------------------
+// Section extraction helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Split file content into three parts: before, lore section body, after.
+ * Returns null for section body when no lore markers are found.
+ *
+ * Handles multiple lore sections (from duplication bugs) and all known
+ * start-marker variants (old + new text) by:
+ * - Collecting every lore section span in the file
+ * - Returning `before` = content before the first section
+ * - Returning `after`  = content after the last section (all intermediate
+ *   sections are discarded)
+ * - Returning `section` = body of the first section found (for import
+ *   and shouldImport to read the canonical content)
+ *
+ * This is self-healing: a file with N duplicate sections will be collapsed
+ * to exactly one on the next exportToFile() call.
+ */
+function splitFile(fileContent: string): {
+  before: string;
+  section: string | null;
+  after: string;
+} {
+  // Collect every lore section span in the file, matching all known
+  // start-marker variants (current + historical renamed markers).
+  // Each span records: where the section body begins/ends and where the
+  // full span (including end-marker) ends.
+  type Span = { markerStart: number; bodyStart: number; bodyEnd: number; spanEnd: number };
+  const spans: Span[] = [];
+
+  let searchFrom = 0;
+  while (searchFrom < fileContent.length) {
+    // Find the earliest occurrence of any known start marker
+    let markerStart = -1;
+    let markerLen = 0;
+    for (const marker of ALL_START_MARKERS) {
+      const idx = fileContent.indexOf(marker, searchFrom);
+      if (idx !== -1 && (markerStart === -1 || idx < markerStart)) {
+        markerStart = idx;
+        markerLen = marker.length;
+      }
+    }
+    if (markerStart === -1) break; // no more start markers
+
+    const bodyStart = markerStart + markerLen;
+    const endIdx = fileContent.indexOf(LORE_SECTION_END, bodyStart);
+    if (endIdx === -1) {
+      // Unclosed section — consume to EOF
+      spans.push({ markerStart, bodyStart, bodyEnd: fileContent.length, spanEnd: fileContent.length });
+      break;
+    }
+
+    spans.push({ markerStart, bodyStart, bodyEnd: endIdx, spanEnd: endIdx + LORE_SECTION_END.length });
+    searchFrom = endIdx + LORE_SECTION_END.length;
+  }
+
+  if (spans.length === 0) {
+    return { before: fileContent, section: null, after: "" };
+  }
+
+  // before = everything before the first lore section (start marker not included)
+  // section = body of the first section (used by shouldImport and importFromFile)
+  // after = everything after the LAST lore section's end marker
+  // Any intermediate duplicate sections are discarded.
+  const before = fileContent.slice(0, spans[0].markerStart);
+  const section = fileContent.slice(spans[0].bodyStart, spans[0].bodyEnd);
+  const after = fileContent.slice(spans[spans.length - 1].spanEnd);
+
+  return { before, section, after };
+}
+
+// ---------------------------------------------------------------------------
+// Parse entries from a lore section body (or any markdown block)
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract ParsedFileEntry objects from a markdown section body.
+ * Handles:
+ * - `<!-- lore:UUID -->` markers before bullet points  → id set
+ * - Bare bullet points without markers                → id null
+ * - Category derived from the nearest preceding `### Heading`
+ * - Malformed or non-UUID markers                    → id null (hand-written)
+ * - Duplicate UUIDs                                  → both returned; caller deduplicates
+ */
+export function parseEntriesFromSection(section: string): ParsedFileEntry[] {
+  const lines = section.split("\n");
+  const entries: ParsedFileEntry[] = [];
+  let currentCategory = "pattern";
+  let pendingId: string | null = null;
+
+  for (const raw of lines) {
+    const line = raw.trim();
+
+    // Category heading: ### Decision / ### Gotcha / etc.
+    const headingMatch = line.match(/^###\s+(.+)$/);
+    if (headingMatch) {
+      currentCategory = headingMatch[1].toLowerCase();
+      pendingId = null;
+      continue;
+    }
+
+    // Marker line: <!-- lore:UUID -->
+    const markerMatch = line.match(MARKER_RE);
+    if (markerMatch) {
+      const candidate = markerMatch[1];
+      pendingId = UUID_RE.test(candidate) ? candidate : null;
+      continue;
+    }
+
+    // Bullet entry: * **Title**: Content
+    const bulletMatch = line.match(/^\*\s+\*\*(.+?)\*\*:\s*(.+)$/);
+    if (bulletMatch) {
+      // Unescape remark's markdown escapes (e.g. \< → <, \\ → \).
+      // Without this, each export/import cycle doubles the backslash-escapes,
+      // exponentially inflating stored content.
+      entries.push({
+        id: pendingId,
+        category: currentCategory,
+        title: unescapeMarkdown(bulletMatch[1].trim()),
+        content: unescapeMarkdown(bulletMatch[2].trim()),
+      });
+      pendingId = null; // consume the pending marker
+      continue;
+    }
+
+    // Any non-matching non-empty line resets the pending marker
+    if (line !== "" && !line.startsWith("##") && !line.startsWith("<!--")) {
+      pendingId = null;
+    }
+  }
+
+  return entries;
+}
+
+// ---------------------------------------------------------------------------
+// Content hash (for change detection)
+// ---------------------------------------------------------------------------
+
+function hashSection(section: string): string {
+  let h = 0;
+  for (let i = 0; i < section.length; i++) {
+    h = (Math.imul(31, h) + section.charCodeAt(i)) | 0;
+  }
+  // Convert to unsigned hex string
+  return (h >>> 0).toString(16).padStart(8, "0");
+}
+
+// ---------------------------------------------------------------------------
+// Build the lore section body from DB entries
+// ---------------------------------------------------------------------------
+
+function buildSection(projectPath: string): string {
+  // Export only project-specific entries (cross_project=0, project_id = this project).
+  // Cross-project entries live in the shared DB on each machine and don't belong
+  // in a per-project AGENTS.md — including them would inflate the file with
+  // unrelated knowledge from every other project the user has worked on.
+  const entries = ltm.forProject(projectPath, false);
+  if (!entries.length) {
+    return "\n";
+  }
+
+  // Group entries by category, preserving DB order (confidence DESC, updated_at DESC).
+  const grouped = new Map<string, typeof entries>();
+  for (const e of entries) {
+    const group = grouped.get(e.category) ?? [];
+    group.push(e);
+    grouped.set(e.category, group);
+  }
+
+  // Build the section body by iterating entries directly, emitting each entry
+  // with its own <!-- lore:UUID --> marker. This avoids the title-based Map
+  // deduplication bug where multiple entries with the same title all got the
+  // same UUID marker from the last Map.set() winner.
+  //
+  // Merge-friendliness: entries within each category are sorted alphabetically
+  // by title (case-insensitive) so the ordering is deterministic across all
+  // machines regardless of DB timestamps.  Blank lines between entries give
+  // git unique context lines to anchor changes -- two branches adding entries
+  // with different titles insert at different positions and auto-merge.
+  const out: string[] = [""];
+
+  // Section heading
+  out.push("## Long-term Knowledge");
+
+  for (const [category, items] of [...grouped.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+    out.push("");
+    out.push(`### ${category.charAt(0).toUpperCase() + category.slice(1)}`);
+    out.push("");
+
+    // Sort entries alphabetically by title for deterministic, merge-friendly output.
+    const sorted = [...items].sort((a, b) =>
+      a.title.localeCompare(b.title, undefined, { sensitivity: "base" }),
+    );
+
+    for (let i = 0; i < sorted.length; i++) {
+      if (i > 0) out.push(""); // blank line between entries for git context
+      out.push(`<!-- lore:${sorted[i].id} -->`);
+      // Render the bullet using remark serializer for proper markdown escaping.
+      // serialize(root(ul([liph(...)]))) produces "* **Title**: content\n".
+      // Trim the trailing newline since we join with \n ourselves.
+      const bullet = serialize(
+        root(ul([liph(strong(inline(sorted[i].title)), t(": " + inline(sorted[i].content)))]))
+      ).trimEnd();
+      out.push(bullet);
+    }
+  }
+
+  out.push("");
+  return out.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Export
+// ---------------------------------------------------------------------------
+
+/**
+ * Write current knowledge entries into the AGENTS.md file, preserving all
+ * non-lore content. Creates the file if it doesn't exist.
+ */
+export function exportToFile(input: {
+  projectPath: string;
+  filePath: string;
+}): void {
+  const sectionBody = buildSection(input.projectPath);
+  const newSection =
+    LORE_SECTION_START + sectionBody + LORE_SECTION_END + "\n";
+
+  let fileContent = "";
+  if (existsSync(input.filePath)) {
+    fileContent = readFileSync(input.filePath, "utf8");
+  }
+
+  const { before, after } = splitFile(fileContent);
+
+  // Ensure there's a blank line separator before the section when appending
+  const prefix = before.trimEnd();
+  const prefixWithSep = prefix.length > 0 ? prefix + "\n\n" : "";
+  const suffix = after.trimStart();
+  const suffixWithSep = suffix.length > 0 ? "\n" + suffix : "";
+
+  const result = prefixWithSep + newSection + suffixWithSep;
+
+  mkdirSync(dirname(input.filePath), { recursive: true });
+  writeFileSync(input.filePath, result, "utf8");
+}
+
+// ---------------------------------------------------------------------------
+// shouldImport
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true if the file needs to be imported:
+ * - File exists and has never been processed (no lore markers)
+ * - File exists and its lore section differs from what lore would currently produce
+ */
+export function shouldImport(input: {
+  projectPath: string;
+  filePath: string;
+}): boolean {
+  if (!existsSync(input.filePath)) return false;
+
+  const fileContent = readFileSync(input.filePath, "utf8");
+  const { section } = splitFile(fileContent);
+
+  if (section === null) {
+    // No lore markers — this is a hand-written file that hasn't been imported
+    return fileContent.trim().length > 0;
+  }
+
+  // Compare the file's lore section body against what we'd produce now
+  const expected = buildSection(input.projectPath);
+  return hashSection(section) !== hashSection(expected);
+}
+
+// ---------------------------------------------------------------------------
+// Import
+// ---------------------------------------------------------------------------
+
+/**
+ * Import knowledge entries from the agents file into the local DB.
+ *
+ * Behaviour per entry:
+ * - Known UUID (already in DB)  → update content if it changed (manual edit)
+ * - Unknown UUID (other machine)→ create with that exact ID
+ * - No UUID (hand-written)      → create with a new UUIDv7
+ * - Duplicate UUID in same file → first occurrence wins, rest ignored
+ */
+export function importFromFile(input: {
+  projectPath: string;
+  filePath: string;
+}): void {
+  if (!existsSync(input.filePath)) return;
+
+  const fileContent = readFileSync(input.filePath, "utf8");
+  const { section, before } = splitFile(fileContent);
+
+  // Determine what to parse:
+  // - If lore markers exist: parse ONLY the lore section body (avoid re-importing our own output)
+  // - If no markers: parse the full file (first-time hand-written AGENTS.md import)
+  const textToParse = section ?? fileContent;
+
+  const fileEntries = parseEntriesFromSection(textToParse);
+  if (!fileEntries.length) return;
+
+  const seenIds = new Set<string>();
+
+  for (const entry of fileEntries) {
+    if (entry.id !== null) {
+      // Deduplicate: if same UUID appears twice in file, first wins
+      if (seenIds.has(entry.id)) continue;
+      seenIds.add(entry.id);
+
+      const existing = ltm.get(entry.id);
+      if (existing) {
+        // Known entry — update only if content changed (manual edit in file)
+        if (existing.content !== entry.content) {
+          ltm.update(entry.id, { content: entry.content });
+        }
+      } else {
+        // Unknown UUID — entry came from another machine, preserve its ID
+        ltm.create({
+          projectPath: input.projectPath,
+          category: entry.category,
+          title: entry.title,
+          content: entry.content,
+          scope: "project",
+          crossProject: false,
+          id: entry.id,
+        });
+      }
+    } else {
+      // Hand-written entry — create with a new UUIDv7
+      // Check for a near-duplicate by title to avoid double-import on re-runs
+      const existing = ltm.forProject(input.projectPath, true);
+      const titleMatch = existing.find(
+        (e) => e.title.toLowerCase() === entry.title.toLowerCase(),
+      );
+      if (!titleMatch) {
+        ltm.create({
+          projectPath: input.projectPath,
+          category: entry.category,
+          title: entry.title,
+          content: entry.content,
+          scope: "project",
+          crossProject: false,
+        });
+      }
+    }
+  }
+}