@rohirik/openltm-core 2.12.0 → 2.12.3

package/README.md

@@ -22,6 +22,7 @@ idempotent — safe to run multiple times.
 
 - Adds the `ltm` MCP server entry (`bunx @rohirik/openltm-core mcp-serve`)
 - Wires three lifecycle hooks: `SessionStart`, `PreCompact`, `PostEditCheck`
+- `SessionStart` now emits a portable Prior Knowledge prefill directly from `openltm-core`; the other two are safe no-ops unless the full Claude plugin checkout is installed
 
 ### OpenCode (`opencode.json`)
 
@@ -54,6 +55,8 @@ config directories.
 
 ## Programmatic API
 
+Installers are registry-driven under `INSTALL_TARGETS`, so adding a new host now means defining one target entry (detect + install) instead of editing the CLI orchestrator in multiple places.
+
 ```typescript
 import { installClaude, installOpenCode, installPi, detectAgents } from "@rohirik/openltm-core/cli";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohirik/openltm-core",
-  "version": "2.12.0",
+  "version": "2.12.3",
   "description": "Shared LTM storage engine — path-agnostic SQLite core used by Claude Code, OpenCode, and Pi adapters",
   "type": "module",
   "main": "./src/index.ts",
@@ -32,7 +32,7 @@
   "dependencies": {
     "@clack/prompts": "^1.3.0",
     "@iarna/toml": "^2.2.5",
-    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "bun-types": "^1.0.0",
     "sqlite-vec": "0.1.9",
     "zod": "^4.3.6"

package/src/__tests__/cli/hook.test.ts

@@ -0,0 +1,47 @@
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import { Database } from "bun:sqlite";
+import { readFileSync, unlinkSync } from "fs";
+import { join } from "path";
+
+const dbPath = `/tmp/test-openltm-hook-${process.pid}-${Date.now()}.db`;
+const SCHEMA_PATH = join(import.meta.dir, "..", "..", "schema.sql");
+
+beforeAll(async () => {
+  const { runPendingMigrations, _setDbForTesting } = await import("../../index.js");
+  const db = new Database(dbPath, { create: true });
+  db.exec("PRAGMA journal_mode=WAL; PRAGMA foreign_keys=ON;");
+  db.exec(readFileSync(SCHEMA_PATH, "utf-8"));
+  await runPendingMigrations(db);
+  _setDbForTesting(db);
+}, 30_000);
+
+afterAll(() => {
+  try { unlinkSync(dbPath); } catch {}
+  try { unlinkSync(`${dbPath}-shm`); } catch {}
+  try { unlinkSync(`${dbPath}-wal`); } catch {}
+});
+
+describe("cli hook dispatcher", () => {
+  it("builds a SessionStart prefill block from hook stdin JSON", async () => {
+    const { learn } = await import("../../index.js");
+    const { buildHookOutput } = await import("../../cli/hook.js");
+
+    learn({
+      content: "SessionStart should restore this memory",
+      category: "pattern",
+      importance: 3,
+      project_scope: "hook-project",
+      skipExport: true,
+    });
+
+    const output = await buildHookOutput("SessionStart", JSON.stringify({ cwd: "/tmp/hook-project" }));
+    expect(output).toContain("Prior Knowledge");
+    expect(output).toContain("restore this memory");
+  });
+
+  it("keeps non-SessionStart hook events as safe no-ops", async () => {
+    const { buildHookOutput } = await import("../../cli/hook.js");
+    expect(await buildHookOutput("PreCompact", JSON.stringify({ cwd: "/tmp/hook-project" }))).toBe("");
+    expect(await buildHookOutput("PostEditCheck", JSON.stringify({ cwd: "/tmp/hook-project" }))).toBe("");
+  });
+});

package/src/__tests__/prefill.test.ts

@@ -0,0 +1,56 @@
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import { Database } from "bun:sqlite";
+import { readFileSync, unlinkSync } from "fs";
+import { join } from "path";
+
+const dbPath = `/tmp/test-openltm-prefill-${process.pid}-${Date.now()}.db`;
+const SCHEMA_PATH = join(import.meta.dir, "..", "schema.sql");
+
+beforeAll(async () => {
+  const { runPendingMigrations, _setDbForTesting } = await import("../index.js");
+  const db = new Database(dbPath, { create: true });
+  db.exec("PRAGMA journal_mode=WAL; PRAGMA foreign_keys=ON;");
+  db.exec(readFileSync(SCHEMA_PATH, "utf-8"));
+  await runPendingMigrations(db);
+  _setDbForTesting(db);
+}, 30_000);
+
+afterAll(() => {
+  try { unlinkSync(dbPath); } catch {}
+  try { unlinkSync(`${dbPath}-shm`); } catch {}
+  try { unlinkSync(`${dbPath}-wal`); } catch {}
+});
+
+describe("prefill helpers", () => {
+  it("returns empty output when no memories exist", async () => {
+    const { buildPrefillContext } = await import("../index.js");
+    expect(buildPrefillContext({ project: "empty-prefill-project", maxMemories: 4 })).toBe("");
+  });
+
+  it("builds a compact shared prefill block from globals + project memories", async () => {
+    const { buildPrefillContext, deriveProjectFromCwd, learn } = await import("../index.js");
+
+    learn({
+      content: "Global guardrail — prefer Bun commands in this repo",
+      category: "workflow",
+      importance: 4,
+      skipExport: true,
+    });
+    learn({
+      content: "Project decision — adapter hooks should use the shared prefill builder",
+      category: "architecture",
+      importance: 3,
+      project_scope: "prefill-project",
+      skipExport: true,
+    });
+
+    expect(deriveProjectFromCwd("/tmp/prefill-project")).toBe("prefill-project");
+
+    const block = buildPrefillContext({ project: "prefill-project", maxMemories: 6, maxLines: 18 });
+    expect(block).toContain("## Prior Knowledge (LTM)");
+    expect(block).toContain("Global:");
+    expect(block).toContain("Project (prefill-project):");
+    expect(block).toContain("prefer Bun commands");
+    expect(block).toContain("shared prefill builder");
+  });
+});

package/src/cli/bin.ts

@@ -9,8 +9,8 @@
  *   bunx @rohirik/openltm-core --pi               # Pi only
  *   bunx @rohirik/openltm-core --dry-run --claude # preview without writing
  *
- *   bunx @rohirik/openltm-core hook --name <hookName>  # lifecycle hook stub
- *   bunx @rohirik/openltm-core mcp-serve               # MCP server (future)
+ *   bunx @rohirik/openltm-core hook --name <hookName>  # lifecycle hook entrypoint
+ *   bunx @rohirik/openltm-core mcp-serve               # MCP server
  */
 import { runInstallCli } from "./install.js";
 import { runHook } from "./hook.js";
@@ -32,7 +32,7 @@ function printHelp(): void {
       "  Sub-commands:",
       "    memory <cmd>          Read/write memories from the shell (learn, recall,",
       "                          forget, relate, context) — run 'memory --help'",
-      "    hook --name <event>   Lifecycle hook stub (for Claude Code hook wiring)",
+      "    hook --name <event>   Lifecycle hook entrypoint (SessionStart prefill + safe no-ops)",
       "    mcp-serve             Start the LTM MCP server (stdio)",
       "",
       "  If no target flags are given, agents are auto-detected.",
@@ -63,7 +63,7 @@ async function main(): Promise<void> {
       process.stderr.write("  ltm hook: missing --name argument\n");
       process.exit(1);
     }
-    runHook(hookName);
+    await runHook(hookName);
     return;
   }
 

package/src/cli/detect.ts

@@ -7,37 +7,9 @@
  *
  * Pure function — accepts a homedir argument so tests can supply a tmp dir.
  */
-import { existsSync } from "fs";
-import { join } from "path";
 import os from "os";
 import type { DetectResult } from "./types.js";
-
-/**
- * Probe for an OpenCode config directory using the standard path resolution
- * order: $XDG_CONFIG_HOME/opencode → ~/.config/opencode → (darwin only)
- * ~/Library/Application Support/opencode.
- */
-function probeOpenCode(homedir: string): boolean {
-  const xdg = process.env["XDG_CONFIG_HOME"];
-  if (xdg && existsSync(join(xdg, "opencode"))) return true;
-  if (existsSync(join(homedir, ".config", "opencode"))) return true;
-  if (process.platform === "darwin") {
-    if (existsSync(join(homedir, "Library", "Application Support", "opencode"))) return true;
-  }
-  return false;
-}
-
-/**
- * Probe for a Pi config using the three known locations:
- * ~/.pi/ | ~/pi.toml | ~/.pi/config.toml
- */
-function probePi(homedir: string): boolean {
-  return (
-    existsSync(join(homedir, ".pi")) ||
-    existsSync(join(homedir, "pi.toml")) ||
-    existsSync(join(homedir, ".pi", "config.toml"))
-  );
-}
+import { INSTALL_TARGETS } from "./targets.js";
 
 /**
  * detectAgents — inspect the filesystem to determine which AI coding agents
@@ -47,9 +19,8 @@ function probePi(homedir: string): boolean {
  * @returns DetectResult with boolean flags for each supported agent.
  */
 export function detectAgents(homedir: string = os.homedir()): DetectResult {
-  return {
-    claude: existsSync(join(homedir, ".claude")),
-    opencode: probeOpenCode(homedir),
-    pi: probePi(homedir),
-  };
+  return INSTALL_TARGETS.reduce<DetectResult>((acc, target) => {
+    acc[target.id] = target.detect(homedir);
+    return acc;
+  }, { claude: false, opencode: false, pi: false });
 }

package/src/cli/hook.ts

@@ -1,25 +1,63 @@
 /**
- * cli/hook.ts — Hook dispatcher stub.
+ * cli/hook.ts — Lightweight Claude-compatible hook dispatcher.
  *
- * Full hook logic lives in the Claude Code plugin (hooks/src/).
- * When invoked via `bunx @rohirik/openltm-core hook --name <hookName>`, this
- * stub exits cleanly (exit 0) so Claude Code does not treat the absent hook
- * runner as an error.
- *
- * A future phase can wire actual hook logic here once openltm-core ships the
- * compiled hook handlers.
+ * For bunx installs we support a portable SessionStart prefill directly from
+ * openltm-core so users still get an "already pre-filled" experience without
+ * the full Claude plugin checkout. Other hook events are safe no-ops.
  */
+import { buildPrefillContext, deriveProjectFromCwd } from "../prefill.js";
+
+function parseHookCwd(raw: string): string {
+  if (!raw.trim()) return "";
+  try {
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    const cwd = parsed["cwd"]
+      ?? parsed["working_directory"]
+      ?? (parsed["session"] as Record<string, unknown> | undefined)?.["cwd"];
+    return typeof cwd === "string" ? cwd : "";
+  } catch {
+    return "";
+  }
+}
+
+export async function buildHookOutput(name: string, rawInput: string): Promise<string> {
+  switch (name) {
+    case "SessionStart": {
+      const cwd = parseHookCwd(rawInput);
+      if (!cwd) return "";
+      const project = deriveProjectFromCwd(cwd);
+      if (!project) return "";
+      return buildPrefillContext({ project, maxMemories: 10, maxLines: 18 });
+    }
+    case "PreCompact":
+    case "PostEditCheck":
+      return "";
+    default:
+      return "";
+  }
+}
+
+async function readStdin(): Promise<string> {
+  let result = "";
+  try {
+    for await (const chunk of Bun.stdin.stream()) {
+      result += new TextDecoder().decode(chunk);
+    }
+  } catch {
+    // stdin may be absent in some hook invocations
+  }
+  return result;
+}
 
 /**
- * runHook — stub dispatcher for LTM lifecycle hooks.
+ * runHook — dispatch a lifecycle hook.
  *
- * @param name - Hook event name (e.g. "SessionStart", "PreCompact").
+ * SessionStart emits a compact Prior Knowledge block when memories exist.
+ * Other events intentionally no-op until a richer host-independent contract is
+ * extracted from the full Claude plugin hook suite.
  */
-export function runHook(name: string): void {
-  // Stub: full hook logic requires the Claude Code plugin.
-  // Exit 0 so Claude Code does not break when the hook is registered.
-  process.stderr.write(
-    `LTM: hook '${name}' via bunx not yet supported — install the Claude Code plugin for full hook support\n`,
-  );
-  process.exit(0);
+export async function runHook(name: string): Promise<void> {
+  const raw = await readStdin();
+  const output = await buildHookOutput(name, raw);
+  if (output) process.stdout.write(output);
 }

package/src/cli/index.ts

@@ -20,3 +20,5 @@ export { detectAgents } from "./detect.js";
 export { installClaude } from "./claude.js";
 export { installOpenCode } from "./opencode.js";
 export { installPi } from "./pi.js";
+export { INSTALL_TARGETS, getInstallTarget } from "./targets.js";
+export type { InstallTargetDefinition } from "./targets.js";

package/src/cli/install.ts

@@ -11,11 +11,9 @@
  */
 import * as clack from "@clack/prompts";
 import { detectAgents } from "./detect.js";
-import { installClaude } from "./claude.js";
-import { installOpenCode } from "./opencode.js";
-import { installPi } from "./pi.js";
 import type { CliInstallOptions, CliInstallResult, InstallStep, InstallResult } from "./types.js";
 import { InstallTarget } from "./types.js";
+import { INSTALL_TARGETS } from "./targets.js";
 
 // ── Known targets set (legacy validation) ────────────────────────────────────
 
@@ -124,53 +122,19 @@ export async function runInstallCli(opts: CliRunOpts): Promise<CliRunResult> {
 
   const results: InstallResult[] = [];
 
-  // Claude
-  if (targets.claude) {
+  for (const target of INSTALL_TARGETS) {
+    if (!targets[target.id]) continue;
     const s = silent ? null : clack.spinner();
-    if (s) s.start("Installing into Claude Code…");
-    const r = await installClaude({ homedir, dryRun });
+    if (s) s.start(`Installing into ${target.label}…`);
+    const r = await target.install({ homedir, dryRun });
     results.push(r);
     if (s) {
       if (r.status === "installed") {
-        s.stop(`Claude Code: installed${dryRun ? " (dry-run)" : ""}`);
+        s.stop(`${target.label}: installed${dryRun ? " (dry-run)" : ""}`);
       } else if (r.status === "skipped") {
-        s.stop("Claude Code: already configured (skipped)");
+        s.stop(`${target.label}: already configured (skipped)`);
       } else {
-        s.stop(`Claude Code: error — ${r.detail ?? "unknown error"}`);
-      }
-    }
-  }
-
-  // OpenCode
-  if (targets.opencode) {
-    const s = silent ? null : clack.spinner();
-    if (s) s.start("Installing into OpenCode…");
-    const r = await installOpenCode({ homedir, dryRun });
-    results.push(r);
-    if (s) {
-      if (r.status === "installed") {
-        s.stop(`OpenCode: installed${dryRun ? " (dry-run)" : ""}`);
-      } else if (r.status === "skipped") {
-        s.stop("OpenCode: already configured (skipped)");
-      } else {
-        s.stop(`OpenCode: error — ${r.detail ?? "unknown error"}`);
-      }
-    }
-  }
-
-  // Pi
-  if (targets.pi) {
-    const s = silent ? null : clack.spinner();
-    if (s) s.start("Installing into Pi…");
-    const r = await installPi({ dryRun });
-    results.push(r);
-    if (s) {
-      if (r.status === "installed") {
-        s.stop(`Pi: installed${dryRun ? " (dry-run)" : ""}`);
-      } else if (r.status === "skipped") {
-        s.stop("Pi: already configured (skipped)");
-      } else {
-        s.stop(`Pi: error — ${r.detail ?? "unknown error"}`);
+        s.stop(`${target.label}: error — ${r.detail ?? "unknown error"}`);
       }
     }
   }

package/src/cli/targets.ts

@@ -0,0 +1,62 @@
+import type { InstallResult } from "./types.js";
+import { installClaude } from "./claude.js";
+import { installOpenCode } from "./opencode.js";
+import { installPi } from "./pi.js";
+import { existsSync } from "fs";
+import { join } from "path";
+
+export interface InstallTargetDefinition {
+  id: "claude" | "opencode" | "pi";
+  label: string;
+  detect: (homedir: string) => boolean;
+  install: (opts: { homedir?: string; dryRun?: boolean }) => Promise<InstallResult>;
+}
+
+function detectClaude(homedir: string): boolean {
+  return existsSync(join(homedir, ".claude"));
+}
+
+function detectOpenCode(homedir: string): boolean {
+  const xdg = process.env["XDG_CONFIG_HOME"];
+  if (xdg && existsSync(join(xdg, "opencode"))) return true;
+  if (existsSync(join(homedir, ".config", "opencode"))) return true;
+  if (process.platform === "darwin") {
+    if (existsSync(join(homedir, "Library", "Application Support", "opencode"))) return true;
+  }
+  return false;
+}
+
+function detectPi(homedir: string): boolean {
+  return (
+    existsSync(join(homedir, ".pi")) ||
+    existsSync(join(homedir, "pi.toml")) ||
+    existsSync(join(homedir, ".pi", "config.toml"))
+  );
+}
+
+export const INSTALL_TARGETS: readonly InstallTargetDefinition[] = [
+  {
+    id: "claude",
+    label: "Claude Code",
+    detect: detectClaude,
+    install: ({ homedir, dryRun }) => installClaude({ homedir, dryRun }),
+  },
+  {
+    id: "opencode",
+    label: "OpenCode",
+    detect: detectOpenCode,
+    install: ({ homedir, dryRun }) => installOpenCode({ homedir, dryRun }),
+  },
+  {
+    id: "pi",
+    label: "Pi",
+    detect: detectPi,
+    install: ({ dryRun }) => installPi({ dryRun }),
+  },
+] as const;
+
+export function getInstallTarget(id: InstallTargetDefinition["id"]): InstallTargetDefinition {
+  const target = INSTALL_TARGETS.find((entry) => entry.id === id);
+  if (!target) throw new Error(`Unknown install target: ${id}`);
+  return target;
+}

package/src/index.ts

@@ -43,6 +43,10 @@ export { categorise } from "./recall/categorise.js";
 export { buildExplainer, computeTemperature } from "./recall/explainer.js";
 export type { MemoryTemperature, RecallExplainer, ExplainerInput } from "./recall/explainer.js";
 
+// Session prefill helpers
+export { buildPrefillContext, deriveProjectFromCwd, selectPrefillMemories } from "./prefill.js";
+export type { PrefillOptions, PrefillSelection } from "./prefill.js";
+
 // Embedding providers
 export * from "./providers/index.js";
 export { WriteQueue, writeQueue } from "./lib/writeQueue.js";

package/src/prefill.ts

@@ -0,0 +1,89 @@
+/**
+ * prefill.ts — Shared session-start context builder for host adapters.
+ *
+ * Keeps the "already pre-filled" experience consistent across Claude Code,
+ * OpenCode, Pi, and any future host that can call into openltm-core.
+ */
+import { getContextMerge, type Memory } from "./db.js";
+import { readConfigSync } from "./config.js";
+
+export interface PrefillOptions {
+  project: string;
+  maxMemories?: number;
+  maxGlobalMemories?: number;
+  maxLines?: number;
+  header?: string;
+}
+
+export interface PrefillSelection {
+  globals: Memory[];
+  scoped: Memory[];
+}
+
+const DEFAULT_HEADER = "## Prior Knowledge (LTM)";
+
+function oneLine(text: string): string {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+function clampPositiveInt(value: number | undefined, fallback: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 1) return fallback;
+  return Math.floor(value);
+}
+
+function formatMemory(memory: Pick<Memory, "id" | "content" | "category" | "importance">): string {
+  return `- [${memory.id}] (${memory.category}/${memory.importance}) ${oneLine(memory.content)}`;
+}
+
+function trimLines(lines: string[], maxLines: number): string[] {
+  if (lines.length <= maxLines) return lines;
+  const trimmed = lines.slice(0, Math.max(0, maxLines - 1));
+  trimmed.push("… (truncated)");
+  return trimmed;
+}
+
+export function deriveProjectFromCwd(cwd: string): string {
+  return cwd.replace(/\/$/, "").split("/").pop() ?? "";
+}
+
+export function selectPrefillMemories(project: string, opts: Omit<PrefillOptions, "project"> = {}): PrefillSelection {
+  const cfg = readConfigSync();
+  const configuredTopN = cfg.ltm?.injectTopN;
+  const maxMemories = clampPositiveInt(opts.maxMemories, configuredTopN ?? 8);
+  const desiredGlobals = clampPositiveInt(opts.maxGlobalMemories, Math.min(3, Math.max(1, Math.ceil(maxMemories / 3))));
+
+  const merged = getContextMerge(project);
+
+  const globals = merged.globals.slice(0, Math.min(desiredGlobals, maxMemories));
+  const remaining = Math.max(0, maxMemories - globals.length);
+  const scoped = merged.scoped.slice(0, remaining);
+
+  if (scoped.length < remaining && globals.length < maxMemories) {
+    const refillGlobals = merged.globals.slice(globals.length, Math.min(merged.globals.length, maxMemories - scoped.length));
+    globals.push(...refillGlobals);
+  }
+
+  return { globals, scoped };
+}
+
+export function buildPrefillContext(opts: PrefillOptions): string {
+  const maxLines = clampPositiveInt(opts.maxLines, 18);
+  const { globals, scoped } = selectPrefillMemories(opts.project, opts);
+  if (globals.length === 0 && scoped.length === 0) return "";
+
+  const lines: string[] = [opts.header ?? DEFAULT_HEADER, ""];
+
+  if (globals.length > 0) {
+    lines.push("Global:");
+    for (const memory of globals) lines.push(formatMemory(memory));
+    lines.push("");
+  }
+
+  if (scoped.length > 0) {
+    lines.push(`Project (${opts.project}):`);
+    for (const memory of scoped) lines.push(formatMemory(memory));
+    lines.push("");
+  }
+
+  return trimLines(lines, maxLines).join("\n").trimEnd() + "\n";
+}

package/src/recall/explainer.ts

@@ -27,6 +27,10 @@ export interface ExplainerInput {
   semanticScore?: number | null;
 }
 
+function roundScore(value: number): number {
+  return Math.round(value * 1_000_000) / 1_000_000;
+}
+
 /** Compute memory temperature from access pattern. */
 export function computeTemperature(
   recallCount: number,
@@ -49,7 +53,7 @@ export function buildExplainer(input: ExplainerInput): RecallExplainer {
   const daysSince = input.last_recalled_at
     ? (Date.now() - new Date(input.last_recalled_at).getTime()) / 86_400_000
     : 90;
-  const recencyBoost = Math.max(0, 1 - daysSince / 90);
+  const recencyBoost = roundScore(Math.max(0, 1 - daysSince / 90));
 
   const ftsRank = input.ftsRank ?? null;
   const semanticScore = input.semanticScore ?? null;
@@ -70,7 +74,7 @@ export function buildExplainer(input: ExplainerInput): RecallExplainer {
     semanticScore,
     importanceBoost,
     recencyBoost,
-    totalScore,
+    totalScore: roundScore(totalScore),
     temperature: computeTemperature(input.recall_count, input.last_recalled_at),
   };
 }