feat: per-prompt relevance injection (v0.1.0)

The engine now embeds each prompt and ranks the workspace's memories, rules, and
skills, so the hook delivers only the few most relevant full bodies per turn with
a graceful lexical fallback. Cross-lingual matching leans on embeddings; the
local backend stays cloud-free behind the KnowledgeBackend seam.

Signed-off-by: Sertan Helvacı <sertanhelvaci@icloud.com>

Author: sertanhelvaci

README.md

@@ -136,10 +136,12 @@ call that provider):
 | Env var | Enables | Without it |
 | --- | --- | --- |
 | `PATHRULE_AI_ROUTE_KEY` (Anthropic) | LLM intent routing for sharper context-depth selection | deterministic router (default, instant) |
-| `PATHRULE_EMBEDDING_PROVIDER` = `voyage` \| `openai` + `PATHRULE_EMBEDDING_API_KEY` | Semantic memory search: embeddings computed on write, cosine-ranked at query time, stored locally | lexical + path-scoped retrieval |
+| `PATHRULE_EMBEDDING_PROVIDER` = `voyage` \| `openai` + `PATHRULE_EMBEDDING_API_KEY` | Semantic relevance, two places: (1) `get_context` memory search, and (2) the hooks — each prompt is embedded and the most relevant memory/skill bodies are ranked and injected just-in-time. Embeddings are computed on write and stored locally; only the prompt is embedded at runtime. | lexical + path-scoped retrieval (hooks still inject, ranked by keyword overlap instead of meaning) |
 
 Both degrade gracefully. On timeout or a missing key, Pathrule falls back to the deterministic
-path, the same fallback discipline the cloud edition uses.
+path, the same fallback discipline the cloud edition uses. The embedding key is what turns the
+hooks from "inject the path's titles" into "inject the few bodies this prompt actually needs," so
+it is the highest-leverage key for context quality and token cost.
 
 ## 🏷 Editions
 

packages/cli-local/src/hook-script-install.ts

@@ -28,11 +28,16 @@ import { atomicWrite } from "@pathrule/shared/local-runtime/atomic-write.js";
 import { cliPlatform } from "./platform.js";
 
 declare const __BUILD_HOOK_SCRIPT_SOURCE__: string;
+declare const __BUILD_EMBED_HELPER_SOURCE__: string;
 
 // In tests / dev / type-checking the define is not substituted; fall back
 // to an empty string so we can mock or read the source from disk.
 const EMBEDDED_HOOK_SCRIPT: string =
   typeof __BUILD_HOOK_SCRIPT_SOURCE__ === "string" ? __BUILD_HOOK_SCRIPT_SOURCE__ : "";
+// The prompt-embedding helper the hook spawns for relevance ranking. Written
+// next to the hook; if absent the hook degrades to lexical ranking.
+const EMBEDDED_EMBED_HELPER: string =
+  typeof __BUILD_EMBED_HELPER_SOURCE__ === "string" ? __BUILD_EMBED_HELPER_SOURCE__ : "";
 
 const WINDOWS_CMD_SHIM = `@echo off
 node "%~dp0pathrule-hook.js" %*
@@ -52,6 +57,8 @@ export interface HookScriptInstallResult {
 export interface HookScriptInstallOptions {
   /** Override the embedded script source (tests only). */
   scriptSource?: string;
+  /** Override the embedded embed-query.cjs source (tests only). */
+  embedHelperSource?: string;
 }
 
 /**
@@ -65,6 +72,7 @@ export function resolveCliHookScriptPaths(env: NodeJS.ProcessEnv = process.env):
   scriptPath: string;
   shimPath: string | null;
   hookCommandPath: string;
+  embedHelperPath: string;
 } {
   const platform = cliPlatform(env);
   const home = pathruleHome(env);
@@ -73,7 +81,8 @@ export function resolveCliHookScriptPaths(env: NodeJS.ProcessEnv = process.env):
   const shimPath =
     platform === "win32" ? joinPathForPlatform(platform, binDir, "pathrule-hook.cmd") : null;
   const hookCommandPath = platform === "win32" && shimPath ? shimPath : scriptPath;
-  return { binDir, scriptPath, shimPath, hookCommandPath };
+  const embedHelperPath = joinPathForPlatform(platform, binDir, "embed-query.cjs");
+  return { binDir, scriptPath, shimPath, hookCommandPath, embedHelperPath };
 }
 
 /**
@@ -85,7 +94,8 @@ export async function installCliHookScript(
   env: NodeJS.ProcessEnv = process.env,
   opts: HookScriptInstallOptions = {},
 ): Promise<HookScriptInstallResult> {
-  const { binDir, scriptPath, shimPath, hookCommandPath } = resolveCliHookScriptPaths(env);
+  const { binDir, scriptPath, shimPath, hookCommandPath, embedHelperPath } =
+    resolveCliHookScriptPaths(env);
   const platform = cliPlatform(env);
   const source = opts.scriptSource ?? EMBEDDED_HOOK_SCRIPT;
 
@@ -99,6 +109,14 @@ export async function installCliHookScript(
 
   // atomicWrite (via writeIfChanged) creates the parent dir, so no explicit mkdir.
   const changed = await writeIfChanged(scriptPath, source);
+
+  // Write the embed helper next to the hook. Best-effort: an empty source (dev /
+  // type-check, where the define is not substituted) just skips the write — the
+  // hook then degrades to lexical ranking rather than failing the whole sync.
+  const embedSource = opts.embedHelperSource ?? EMBEDDED_EMBED_HELPER;
+  if (embedSource && embedSource.length > 0) {
+    await writeIfChanged(embedHelperPath, embedSource);
+  }
   if (platform !== "win32") {
     // Best-effort executable bit so users running the script directly get
     // a friendly error instead of "permission denied".

packages/cli-local/src/local/sync-local.test.ts

@@ -7,6 +7,7 @@ import { describe, it, expect, afterEach } from "vitest";
 import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { LocalBackend } from "@pathrule/core";
 import { initLocalWorkspace } from "./init-local.js";
 import { syncLocalWorkspace } from "./sync-local.js";
 
@@ -74,6 +75,54 @@ describe("syncLocalWorkspace", () => {
     expect(existsSync(join(cwd, ".pathrule/managed-files.json"))).toBe(true);
   });
 
+  it("renders the per-directory compiled knowledge files from the local store — no login", async () => {
+    const home = freshDir("pathrule-cli-home-");
+    const cwd = freshDir("pathrule-cli-ws-");
+    const env = { PATHRULE_HOME: home } as NodeJS.ProcessEnv;
+
+    const ws = await initLocalWorkspace({ cwd, env, genWorkspaceId: () => "ws-knowledge" });
+
+    // Seed knowledge: a root-scoped memory + a path-scoped one under /src.
+    const backend = LocalBackend.openForWorkspace(ws.workspaceId, env);
+    try {
+      const root = await backend.ensureNodeForPath(ws.workspaceId, "/");
+      await backend.writeMemory({
+        workspaceId: ws.workspaceId,
+        nodeId: root.id,
+        title: "Root convention",
+        content: "Always run pnpm typecheck before committing.",
+      });
+      const src = await backend.ensureNodeForPath(ws.workspaceId, "/src");
+      await backend.writeMemory({
+        workspaceId: ws.workspaceId,
+        nodeId: src.id,
+        title: "Src module rule",
+        content: "Components live under src and export via index.ts.",
+      });
+    } finally {
+      backend.close();
+    }
+
+    const result = await syncLocalWorkspace(env, cwd, ws.workspaceId, {
+      hookScriptSource: HOOK_SCRIPT_SOURCE,
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.companion.ok).toBe(true);
+    expect(result.companion.written).toBeGreaterThan(0);
+
+    // Root-scoped knowledge → .claude/rules/pathrule-knowledge.md.
+    const rootKnowledge = readFileSync(
+      join(cwd, ".claude/rules/pathrule-knowledge.md"),
+      "utf8",
+    );
+    expect(rootKnowledge).toContain("Root convention");
+
+    // Path-scoped knowledge → src/CLAUDE.md (Claude Code's native lazy-load channel).
+    const srcClaudeMd = readFileSync(join(cwd, "src/CLAUDE.md"), "utf8");
+    expect(srcClaudeMd).toContain("Src module rule");
+  });
+
   it("is idempotent — a second run rewrites nothing", async () => {
     const home = freshDir("pathrule-cli-home-");
     const cwd = freshDir("pathrule-cli-ws-");

packages/cli-local/src/local/sync-local.ts

@@ -6,21 +6,24 @@
 //      also registers the hook command path the settings merger writes),
 //   2. install the Pre/Post/UserPromptSubmit hook into <cwd>/.claude/settings.json
 //      via the pure settings merger,
-//   3. write the static `.claude/rules/pathrule-protocol.md` (no backend needed;
-//      the dynamic CLAUDE.md render is deliberately skipped — the hook-index
-//      already injects path context),
-//   4. warm `~/.pathrule/cache/<ws>/hook-index.json` from the LocalBackend.
+//   3. write the static `.claude/rules/pathrule-protocol.md` (no backend needed),
+//   4. render the per-directory compiled knowledge files (claude-code's
+//      CLAUDE.md + .claude/rules/pathrule-knowledge.md, plus the other enabled
+//      clients' files) from the LocalBackend — brings the native
+//      compilation win to the no-login edition (MCP-less, turn-zero path context),
+//   5. warm `~/.pathrule/cache/<ws>/hook-index.json` from the LocalBackend.
 //
 // No org, no auth, no remote calls, no preflight. Idempotent — every step is
 // write-if-changed or a fresh assembly.
 
 import { join } from "node:path";
 
-import { LocalBackend } from "@pathrule/core";
+import { LocalBackend, resolveLocalPrincipal } from "@pathrule/core";
 import {
   ensureClaudeSettingsHook,
   renderProtocolRulesFile,
 } from "@pathrule/shared/pathrule-protocol.js";
+import { rerenderMultiClientLocal } from "@pathrule/shared/client-renderers/pipeline.js";
 import { atomicWrite, readIfExists } from "@pathrule/shared/local-runtime/atomic-write.js";
 import {
   syncHookIndex,
@@ -46,6 +49,15 @@ export interface LocalSyncResult {
     skipped: number;
     errors: Array<{ path: string; message: string }>;
   };
+  companion: {
+    ok: boolean;
+    enabled: string[];
+    written: number;
+    skipped: number;
+    removed: number;
+    errors: Array<{ path: string; message: string }>;
+    error?: string;
+  };
   hook_index: HookIndexSyncResult;
   error?: string;
 }
@@ -138,9 +150,42 @@ export async function syncLocalWorkspace(
     });
   }
 
-  // 4. Warm the offline hook-index from the local store.
+  // 4 + 5 share one LocalBackend handle: render the per-directory compiled
+  // knowledge files, then warm the offline hook-index from the same store.
+  let companion: LocalSyncResult["companion"];
   let hookIndex: HookIndexSyncResult;
   const backend = LocalBackend.openForWorkspace(workspaceId, env);
+  try {
+    const outcome = await rerenderMultiClientLocal({
+      backend,
+      workspaceId,
+      workspaceName: backend.getWorkspaceName(workspaceId) ?? workspaceId,
+      workspaceRoot: cwd,
+      userId: resolveLocalPrincipal(env),
+      runtimeOwner: CLI_MANAGED_FILE_OWNER,
+      runtimeVersion: CLI_VERSION,
+    });
+    companion = {
+      ok: outcome.ok,
+      enabled: outcome.enabled,
+      written: outcome.disk.written,
+      skipped: outcome.disk.skipped,
+      removed: outcome.disk.removed,
+      errors: outcome.disk.errors,
+      error: outcome.error,
+    };
+  } catch (err) {
+    companion = {
+      ok: false,
+      enabled: [],
+      written: 0,
+      skipped: 0,
+      removed: 0,
+      errors: [],
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+
   try {
     hookIndex = await syncHookIndex({
       backend,
@@ -160,20 +205,24 @@ export async function syncLocalWorkspace(
     backend.close();
   }
 
-  const ok = hookScript.ok && files.errors.length === 0 && hookIndex.ok;
+  const ok =
+    hookScript.ok && files.errors.length === 0 && companion.ok && hookIndex.ok;
   return {
     ok,
     workspace_id: workspaceId,
     workspace_root: cwd,
     hook_script: hookScript,
     files,
+    companion,
     hook_index: hookIndex,
     error: ok
       ? undefined
       : !hookScript.ok
         ? "hook_script_install_failed"
         : files.errors.length > 0
           ? "local_file_sync_failed"
-          : "hook_index_sync_failed",
+          : !companion.ok
+            ? "companion_render_failed"
+            : "hook_index_sync_failed",
   };
 }

packages/core/package.json

@@ -5,10 +5,12 @@
   "private": true,
   "license": "Apache-2.0",
   "type": "module",
+  "sideEffects": false,
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./backend/knowledge-compiler.js": "./src/backend/knowledge-compiler.ts"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

packages/core/src/backend/contract-suite.ts

@@ -743,6 +743,13 @@ export function runKnowledgeBackendContract(
         expect(idx!.skill_invocation_index?.["deploy"]?.[0]?.name).toBe("Deploy");
         expect(idx!.filename_index?.["config.json"]).toContain(mem.id);
         expect(idx!.pending_refresh_count).toBe(0);
+
+        // The warehouse carries FULL bodies keyed by id, with content_hash
+        // matching the index stub (so the delta gate can compare).
+        const warehouse = await b.buildWarehousePayload?.(WS);
+        expect(warehouse).toBeTruthy();
+        expect(warehouse![mem.id]).toMatchObject({ type: "memory", title: "config.json setup", body: "how to configure" });
+        expect(warehouse![mem.id]!.content_hash).toBe(idx!.path_memories["/api"]![0]!.content_hash);
       });
 
       it("logActivity returns the persisted row, defaults node_path, and normalizes subjects", async () => {
@@ -888,6 +895,41 @@ export function runKnowledgeBackendContract(
         expect(res?.payload?.searched_scope.matched_node_path).toBe("/");
       });
 
+      it("buildEmbeddingsPayload projects the on-write store: id→vector, active only", async () => {
+        const b = makeBackend();
+        if (!b.capabilities().semantic || !b.buildEmbeddingsPayload) return;
+        const alpha = await b.writeMemory({
+          workspaceId: WS,
+          nodeId: "n1",
+          title: "alpha topic",
+          content: "all about alpha",
+        });
+        const beta = await b.writeMemory({
+          workspaceId: WS,
+          nodeId: "n1",
+          title: "beta topic",
+          content: "beta beta",
+        });
+        // Skills are embedded on demand into the same payload.
+        const skill = await b.writeSkill({
+          workspaceId: WS,
+          name: "alpha skill",
+          content: "all about alpha",
+        });
+        const payload = await b.buildEmbeddingsPayload(WS);
+        expect(payload).toBeTruthy();
+        expect(Object.keys(payload!).sort()).toEqual([alpha.id, beta.id, skill.id].sort());
+        expect(payload![alpha.id]).toHaveLength(3); // CONTRACT_TEST_EMBED dims
+        expect(payload![skill.id]).toHaveLength(3); // skill embedded too
+        expect(Array.isArray(payload![alpha.id])).toBe(true);
+
+        // A deleted (soft) memory drops out of the payload — both backends join
+        // only active memories; the skill stays.
+        await b.deleteMemory({ id: beta.id });
+        const after = await b.buildEmbeddingsPayload(WS);
+        expect(Object.keys(after ?? {}).sort()).toEqual([alpha.id, skill.id].sort());
+      });
+
       it("drops direct (already-shown) ids and marks lexical overlap on title-only ids", async () => {
         const b = makeBackend();
         if (!b.capabilities().semantic || !b.semanticCandidates) return;