memhook 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to memhook are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0](https://github.com/utilia-ai-wox/memhook/compare/v0.4.1...v0.5.0) (2026-06-03)
+
+
+### Features
+
+* **catalog:** add built-in host presets ([#41](https://github.com/utilia-ai-wox/memhook/issues/41)) ([596aa11](https://github.com/utilia-ai-wox/memhook/commit/596aa112e691bd94348e0883f12f09950bbe1f99))
+* **catalog:** add custom memory sources ([#40](https://github.com/utilia-ai-wox/memhook/issues/40)) ([fde6507](https://github.com/utilia-ai-wox/memhook/commit/fde6507741f89286c20c31d143cc78eb0f5aff0a))
+* **catalog:** add preset discovery command (presets list/detect) ([#42](https://github.com/utilia-ai-wox/memhook/issues/42)) ([9ce7c1c](https://github.com/utilia-ai-wox/memhook/commit/9ce7c1cb7903c5a7cce204dfdec5809bd1f98b09))
+* **catalog:** add presets:[auto] zero-config preset routing ([#44](https://github.com/utilia-ai-wox/memhook/issues/44)) ([9b6f50a](https://github.com/utilia-ai-wox/memhook/commit/9b6f50ad6eeb1576b4e4da3c0542aeac6589dbd1))
+* **catalog:** omit host-autoloaded rule zones by default ([#39](https://github.com/utilia-ai-wox/memhook/issues/39)) ([0b6dee0](https://github.com/utilia-ai-wox/memhook/commit/0b6dee0a274e497c20070cdea22ecee87e6187ba))
+* **router:** add presets nudge for unrouted host memory ([#43](https://github.com/utilia-ai-wox/memhook/issues/43)) ([f76d159](https://github.com/utilia-ai-wox/memhook/commit/f76d159411e0b65d4c7fcfcfb40bad064700df6a))
+* **router:** introduce a harness-adapter seam with Claude Code as adapter [#1](https://github.com/utilia-ai-wox/memhook/issues/1) ([#38](https://github.com/utilia-ai-wox/memhook/issues/38)) ([cebe646](https://github.com/utilia-ai-wox/memhook/commit/cebe646868ca2f502ffeabe9abf9f9ddc97753a3))
+
+
+### Documentation
+
+* clarify the README value proposition ([#36](https://github.com/utilia-ai-wox/memhook/issues/36)) ([f663237](https://github.com/utilia-ai-wox/memhook/commit/f663237de7cd3727db7715faf36309fc83a77fcd))
+
 ## [0.4.1](https://github.com/utilia-ai-wox/memhook/compare/v0.4.0...v0.4.1) (2026-06-02)
 
 

package/README.md

@@ -2,7 +2,7 @@
 
 # memhook
 
-**Stop loading every memory file on every prompt. memhook routes only the relevant ones.**
+**Stop telling Claude to check its memory. memhook auto-injects the notes relevant to each prompt — so it already knows what you told it.**
 
 <p align="center">
   <a href="https://www.npmjs.com/package/memhook"><img src="https://img.shields.io/npm/v/memhook?color=cb3837&logo=npm" alt="npm version"></a>
@@ -14,17 +14,19 @@
 </p>
 
 A semantic memory router for [Claude Code](https://claude.com/claude-code) — a
-`UserPromptSubmit` hook that picks the relevant `feedback_*.md` & `rule_*.md`
-files for each prompt and injects them as `additionalContext`.
+`UserPromptSubmit` hook that picks the `feedback_*.md` & `rule_*.md` notes relevant
+to _this_ prompt and injects them as `additionalContext`. Your memory gets consulted
+automatically — you stop saying _"go read your memory."_
 
 </div>
 
 ## ✨ Features
 
-- 🎯 **Relevant-only injection** — a cheap model picks the 0–5 memory files that matter for _this_ prompt.
-- 💸 **Token-frugal** — skips the 10–14k-token catalog dump; injects ~2k tokens of signal.
+- 🎯 **Right note, right moment** — auto-selects the 0–5 memory files relevant to _this_ prompt and injects them. No more "go read your memory."
+- 🧠 **Gets better as your memory grows** — relevance is picked per prompt, so a large memory helps instead of drowning the model.
 - 🛡️ **Fail-soft** — never blocks Claude Code; every error path falls back to empty context.
 - 🔌 **Multi-provider** — Anthropic (default), OpenAI, or local Ollama. Your key, your endpoint.
+- 💸 **Light on context** — injects ~2k tokens of signal instead of a 10–14k-token catalog dump.
 - 🤫 **Zero telemetry** — the only outbound call is the LLM endpoint _you_ chose.
 - 🪶 **One dependency** — `yaml`, with zero sub-deps.
 - ⚡ **Cached & pre-filtered** — an LRU cache + a trivial-prompt skip keep latency near zero.
@@ -35,17 +37,19 @@ files for each prompt and injects them as `additionalContext`.
 
 Claude Code's `~/.claude/` directory accumulates a growing set of
 `feedback_*.md` (behavioural corrections) and `rule_*.md` (project doctrine)
-files. Loading all of them on every prompt is wasteful — most of it is
-irrelevant to the question at hand.
+files. The problem isn't their size — it's that Claude doesn't know what's in
+there: it misses notes that apply, so you keep telling it _"you wrote that
+down, go read it."_
 
-memhook uses a cheap router model (**Haiku 4.5** by default) to match each
-prompt against a one-line catalog of all your memory files, and injects only
-the most relevant ones. The rest sit on disk, invisible until they matter.
+memhook removes that chore. A cheap router model (**Haiku 4.5** by default)
+matches each prompt against a one-line catalog of all your memory files and
+injects just the relevant ones — so the right note is already in context,
+automatically. The rest sit on disk, invisible until they matter.
 
-| Approach              | Tokens / prompt | Relevance         |
-| --------------------- | --------------- | ----------------- |
-| Load all memory files | 10–14k          | mostly irrelevant |
-| **memhook**           | ~2k             | only what matches |
+| Approach              | What Claude sees                | Tokens / prompt |
+| --------------------- | ------------------------------- | --------------- |
+| Load all memory files | mostly irrelevant noise         | 10–14k          |
+| **memhook**           | only what matches _this_ prompt | ~2k             |
 
 ## 🚀 Quick start
 
@@ -282,7 +286,7 @@ non-negotiable; the [`failsoft-auditor`](.claude/agents/failsoft-auditor.md)
 agent guards it on every PR.
 
 > [!TIP]
-> ⭐ If memhook saves you tokens, **star the repo** — it helps other Claude Code users find it.
+> ⭐ If memhook keeps Claude on-context without the "go read your memory" nudges, **star the repo** — it helps other Claude Code users find it.
 
 ## License
 

package/dist/bin/memhook.js

@@ -17,16 +17,21 @@
  *   "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "memhook run" }] }]
  *   "SessionStart":     [{ "hooks": [{ "type": "command", "command": "memhook build-catalog" }] }]
  */
+import { homedir } from "node:os";
+import { readdirSync } from "node:fs";
 import { route } from "../src/router.js";
 import { buildCatalog } from "../src/catalog.js";
 import { loadConfig } from "../src/config.js";
+import { resolveSources } from "../src/sources.js";
 import { runInit, runUninstall } from "../src/init.js";
 import { runTail } from "../src/tail.js";
 import { runSkills } from "../src/skillsCmd.js";
+import { runPresets } from "../src/presetsCmd.js";
 import { isCompanionSkill } from "../src/skills.js";
 import { MEMHOOK_VERSION as VERSION } from "../src/version.js";
 const PROVIDERS = ["anthropic", "openai", "ollama"];
 const SKILLS_SUBCOMMANDS = ["install", "uninstall", "list"];
+const PRESETS_SUBCOMMANDS = ["list", "detect"];
 async function main() {
     const cmd = process.argv[2] ?? "help";
     const args = process.argv.slice(3);
@@ -49,6 +54,9 @@ async function main() {
         case "skills":
             process.exitCode = await cmdSkills(args);
             break;
+        case "presets":
+            process.exitCode = cmdPresets(args);
+            break;
         case "version":
         case "--version":
         case "-v":
@@ -88,9 +96,12 @@ async function cmdRun() {
 }
 function cmdBuildCatalog() {
     const config = loadConfig();
+    const cwd = process.cwd();
     const result = buildCatalog({
-        cwd: process.cwd(),
+        cwd,
         outputPath: config.catalog.path,
+        resurfaceHostLoaded: config.resurfaceHostLoaded,
+        customSources: resolveSources(config.customSources, config.presets, cwd, homedir(), readdirSync),
     });
     process.stderr.write(`[memhook build-catalog] ${config.catalog.path} — ${result.lines}L, ${result.bytes}B\n`);
 }
@@ -144,6 +155,15 @@ async function cmdSkills(args) {
         force: flags["force"] === true,
     });
 }
+function cmdPresets(args) {
+    const { positionals } = parseArgs(args, BOOL_PRESETS);
+    const sub = positionals[0] ?? "detect";
+    if (!PRESETS_SUBCOMMANDS.includes(sub)) {
+        process.stderr.write(`memhook presets: unknown subcommand "${sub}" (list | detect)\n`);
+        return 1;
+    }
+    return runPresets({ subcommand: sub });
+}
 async function cmdUninstall(args) {
     const { flags } = parseArgs(args, BOOL_UNINSTALL);
     return runUninstall({
@@ -176,6 +196,7 @@ const BOOL_INIT = new Set(["yes", "dry-run", "no-catalog", "skills", "no-skills"
 const BOOL_UNINSTALL = new Set(["yes", "dry-run", "purge"]);
 const BOOL_TAIL = new Set(["no-follow"]);
 const BOOL_SKILLS = new Set(["yes", "dry-run", "force"]);
+const BOOL_PRESETS = new Set([]);
 const SHORT = { "-y": "--yes", "-n": "--lines" };
 function strFlag(v) {
     return typeof v === "string" ? v : undefined;
@@ -240,6 +261,7 @@ COMMANDS
   uninstall          Remove memhook's hooks from ~/.claude/settings.json
   tail               Pretty live view of the routing log (status, latency, memories)
   skills             Install/uninstall/list companion skills (/wrap /curate /relay)
+  presets            List/detect built-in per-host source presets (experimental)
   version            Print version
   help               Show this message
 
@@ -275,6 +297,11 @@ skills SUBCOMMANDS
   --dry-run          print the plan, write nothing
   -y, --yes          non-interactive (accept defaults)
 
+presets SUBCOMMANDS
+  detect             scan this project + home for host memory, print the
+                     'presets: […]' snippet to enable what's found (default)
+  list               show every built-in preset (cline | continue | copilot | windsurf)
+
 ENV VARS
   MEMHOOK_ENABLED                 toggle (default: true)
   MEMHOOK_PROVIDER                anthropic | openai | ollama (default: anthropic)
@@ -288,10 +315,18 @@ ENV VARS
   MEMHOOK_TIMEOUT_MS              request timeout (default: 8000; ollama: 30000)
   MEMHOOK_DISABLE_CACHE=true      skip local LRU cache
   MEMHOOK_DISABLE_PREFILTER=true  skip trivial-prompt skip
+  MEMHOOK_RESURFACE_HOST_LOADED   route rules the host already auto-loads at
+                                  launch (default: false). Enable for long
+                                  sessions / no-drift projects (re-surfaces
+                                  launch-loaded rules near the prompt).
   MEMHOOK_CURATE_NUDGE            /curate-nudge toggle (default: true)
   MEMHOOK_CURATE_NUDGE_TOKENS     catalog-token threshold to nudge (default: 15000)
   MEMHOOK_CURATE_NUDGE_FILES      memory-file-count threshold to nudge (default: 250)
   MEMHOOK_CURATE_NUDGE_COOLDOWN_DAYS  min days between nudges (default: 7)
+  MEMHOOK_PRESETS_NUDGE           presets-nudge toggle (default: true) — suggests
+                                  'memhook presets detect' when a known host's
+                                  memory exists in the project but isn't routed
+  MEMHOOK_PRESETS_NUDGE_COOLDOWN_DAYS  min days between presets nudges (default: 7)
   NO_COLOR / MEMHOOK_NO_COLOR     disable colour in init/tail output
   MEMHOOK_DEBUG=true              print errors to stderr (default: silent fail-soft)
 

package/dist/src/adapters/claudeCode.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Claude Code adapter — memhook's first and reference harness adapter.
+ *
+ * Input  (stdin): the `UserPromptSubmit` hook JSON; only `prompt` + `cwd` are
+ *   used (docs/SPECIFICATION.md §10.1).
+ * Output (stdout): `{ hookSpecificOutput: { hookEventName: "UserPromptSubmit",
+ *   additionalContext }, systemMessage? }` (§10.2). `systemMessage` is emitted
+ *   only when the result carries one (the `/curate` nudge); absent otherwise, so
+ *   the serialised shape is byte-identical to memhook's pre-adapter output.
+ *
+ * Contract source: https://code.claude.com/docs/en/hooks (mirrored in §10).
+ */
+import type { HookOutput } from "../router.js";
+import type { HarnessAdapter } from "./types.js";
+export declare const claudeCodeAdapter: HarnessAdapter<HookOutput>;

package/dist/src/adapters/claudeCode.js

@@ -0,0 +1,49 @@
+/**
+ * Claude Code adapter — memhook's first and reference harness adapter.
+ *
+ * Input  (stdin): the `UserPromptSubmit` hook JSON; only `prompt` + `cwd` are
+ *   used (docs/SPECIFICATION.md §10.1).
+ * Output (stdout): `{ hookSpecificOutput: { hookEventName: "UserPromptSubmit",
+ *   additionalContext }, systemMessage? }` (§10.2). `systemMessage` is emitted
+ *   only when the result carries one (the `/curate` nudge); absent otherwise, so
+ *   the serialised shape is byte-identical to memhook's pre-adapter output.
+ *
+ * Contract source: https://code.claude.com/docs/en/hooks (mirrored in §10).
+ */
+export const claudeCodeAdapter = {
+    id: "claude-code",
+    parseInput(stdinJson) {
+        let parsed;
+        try {
+            parsed = JSON.parse(stdinJson);
+        }
+        catch {
+            return null;
+        }
+        // Guard against non-object payloads (`"null"`, a bare number/string): they
+        // are not usable hook inputs. This keeps `route()` from throwing on them —
+        // a strict tightening of fail-soft, with the same empty output as before.
+        if (typeof parsed !== "object" || parsed === null)
+            return null;
+        const obj = parsed;
+        if (typeof obj.prompt !== "string")
+            return null;
+        const input = { prompt: obj.prompt };
+        // exactOptionalPropertyTypes: only set cwd when the host actually sent one.
+        if (typeof obj.cwd === "string")
+            input.cwd = obj.cwd;
+        return input;
+    },
+    formatOutput(result) {
+        const output = {
+            hookSpecificOutput: {
+                hookEventName: "UserPromptSubmit",
+                additionalContext: result.additionalContext,
+            },
+        };
+        if (result.systemMessage !== undefined) {
+            output.systemMessage = result.systemMessage;
+        }
+        return output;
+    },
+};

package/dist/src/adapters/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Harness adapter contract.
+ *
+ * memhook's selection pipeline is harness-agnostic: it consumes a normalised
+ * `{prompt, cwd}` and produces a `RouteResult`. The ONLY harness-specific
+ * surface is (a) parsing the host's hook stdin into that normalised input and
+ * (b) serialising the result into the host's stdout envelope. A `HarnessAdapter`
+ * captures exactly those two ends, so a new host (Codex, Gemini, …) is an
+ * adapter, not a fork of the router.
+ *
+ * See docs/SPECIFICATION.md §5 (architecture) and §10 (hook contract).
+ */
+/** Normalised hook input. Every adapter maps its host's stdin to this shape. */
+export interface HarnessInput {
+    /** The verbatim user prompt. */
+    prompt: string;
+    /** The project working directory, when the host provides one. */
+    cwd?: string;
+}
+/**
+ * Harness-agnostic outcome of one routing pass. Adapters serialise this into
+ * their host's stdout envelope.
+ */
+export interface RouteResult {
+    /** Context to inject ahead of the user prompt. Empty string = inject nothing. */
+    additionalContext: string;
+    /**
+     * Optional one-line notice to the user (the `/curate` nudge). Absent on every
+     * normal turn, so a host whose envelope has no equivalent simply ignores it.
+     */
+    systemMessage?: string;
+}
+/**
+ * The host-specific surface of the hook. `parseInput` reads the host's stdin
+ * JSON into a `HarnessInput` (or `null` when it isn't a usable hook input);
+ * `formatOutput` serialises a `RouteResult` into the host's stdout shape.
+ */
+export interface HarnessAdapter<TOutput = unknown> {
+    /** Stable identifier, e.g. `"claude-code"`. */
+    readonly id: string;
+    /** Parse the host's hook stdin JSON into `{prompt, cwd}`, or `null` if unusable. */
+    parseInput(stdinJson: string): HarnessInput | null;
+    /** Serialise a routing result into the host's stdout envelope. */
+    formatOutput(result: RouteResult): TOutput;
+}

package/dist/src/adapters/types.js

@@ -0,0 +1,13 @@
+/**
+ * Harness adapter contract.
+ *
+ * memhook's selection pipeline is harness-agnostic: it consumes a normalised
+ * `{prompt, cwd}` and produces a `RouteResult`. The ONLY harness-specific
+ * surface is (a) parsing the host's hook stdin into that normalised input and
+ * (b) serialising the result into the host's stdout envelope. A `HarnessAdapter`
+ * captures exactly those two ends, so a new host (Codex, Gemini, …) is an
+ * adapter, not a fork of the router.
+ *
+ * See docs/SPECIFICATION.md §5 (architecture) and §10 (hook contract).
+ */
+export {};

package/dist/src/catalog.d.ts

@@ -1,17 +1,31 @@
 /**
  * Memhook catalog builder — TS port of build-memory-catalog.sh.
  *
- * Discovers feedbacks & projects in `~/.claude/projects/* /memory/`, global
- * rules in `~/.claude/rules/`, and project rules in `<cwd>/.claude/rules/`.
+ * Discovers feedbacks & projects in `~/.claude/projects/* /memory/`. Global
+ * rules (`~/.claude/rules/`) and project rules (`<cwd>/.claude/rules/`) are
+ * host-autoloaded and included ONLY when `resurfaceHostLoaded` is set (default
+ * off), so memhook does not re-catalogue what Claude Code already loads at
+ * launch.
  *
  * Phase 0.5 Q4: title-only for non-CWD zones (~50% catalog size reduction).
  * The CWD zone gets full `basename: description`; others list just basenames.
  */
+import { type CustomSource } from "./sources.js";
 export interface CatalogBuildOptions {
     cwd: string;
     projectsRoot?: string;
     globalRulesDir?: string;
     outputPath: string;
+    /**
+     * Include the host-autoloaded rule zones (`~/.claude/rules`,
+     * `<cwd>/.claude/rules`) in the catalog. Default `false`: those files are
+     * loaded in full by Claude Code at launch, so cataloguing them would let the
+     * router re-inject what the host already has (double-injection). See
+     * `MemhookConfig.resurfaceHostLoaded`.
+     */
+    resurfaceHostLoaded?: boolean;
+    /** Extra `.md` source dirs to catalog alongside the built-in zones. */
+    customSources?: CustomSource[];
 }
 export declare function buildCatalog(opts: CatalogBuildOptions): {
     lines: number;

package/dist/src/catalog.js

@@ -1,8 +1,11 @@
 /**
  * Memhook catalog builder — TS port of build-memory-catalog.sh.
  *
- * Discovers feedbacks & projects in `~/.claude/projects/* /memory/`, global
- * rules in `~/.claude/rules/`, and project rules in `<cwd>/.claude/rules/`.
+ * Discovers feedbacks & projects in `~/.claude/projects/* /memory/`. Global
+ * rules (`~/.claude/rules/`) and project rules (`<cwd>/.claude/rules/`) are
+ * host-autoloaded and included ONLY when `resurfaceHostLoaded` is set (default
+ * off), so memhook does not re-catalogue what Claude Code already loads at
+ * launch.
  *
  * Phase 0.5 Q4: title-only for non-CWD zones (~50% catalog size reduction).
  * The CWD zone gets full `basename: description`; others list just basenames.
@@ -10,6 +13,7 @@
 import { existsSync, readFileSync, readdirSync, writeFileSync, statSync, renameSync, } from "node:fs";
 import { join, basename as pathBasename } from "node:path";
 import { homedir } from "node:os";
+import { activeCustomSources, listMatchingMdFiles } from "./sources.js";
 export function buildCatalog(opts) {
     const home = homedir();
     const projectsRoot = opts.projectsRoot ?? join(home, ".claude", "projects");
@@ -18,8 +22,22 @@ export function buildCatalog(opts) {
     const sections = [];
     sections.push(emitMemorySection("feedback", "MEMORY FEEDBACKS", memoryDirs));
     sections.push(emitMemorySection("project", "MEMORY PROJECTS", memoryDirs));
-    sections.push(emitRulesSection("GLOBAL RULES", globalRulesDir, true));
-    sections.push(emitRulesSection(`PROJECT RULES (${pathBasename(opts.cwd)})`, join(opts.cwd, ".claude", "rules"), true));
+    // Global + project rules are host-autoloaded: Claude Code reads
+    // `~/.claude/rules/*.md` and `<cwd>/.claude/rules/*.md` in full at launch. By
+    // default memhook leaves them OUT of the catalog so the router never re-routes
+    // what the host already loaded (no double-injection — it routes only the
+    // not-autoloaded `feedback_*/project_*` memory). `resurfaceHostLoaded` adds
+    // them back for positional re-surfacing (long sessions / no-drift projects).
+    if (opts.resurfaceHostLoaded) {
+        sections.push(emitRulesSection("GLOBAL RULES", globalRulesDir, true));
+        sections.push(emitRulesSection(`PROJECT RULES (${pathBasename(opts.cwd)})`, join(opts.cwd, ".claude", "rules"), true));
+    }
+    // User-declared extra sources (cable onto existing project memory). Skipped
+    // when host-autoloaded unless resurfaceHostLoaded — same gate as the rules.
+    const custom = activeCustomSources(opts.customSources ?? [], opts.resurfaceHostLoaded ?? false);
+    if (custom.length > 0) {
+        sections.push(emitCustomSourcesSection(custom));
+    }
     const content = sections.join("\n");
     const tmp = `${opts.outputPath}.tmp.${process.pid}`;
     writeFileSync(tmp, content, "utf8");
@@ -106,6 +124,34 @@ function emitRulesSection(label, dir, isCwdZone) {
     lines.push("");
     return lines.join("\n");
 }
+function emitCustomSourcesSection(sources) {
+    const lines = ["=== CUSTOM SOURCES ==="];
+    let total = 0;
+    for (const src of sources) {
+        let entries;
+        try {
+            entries = readdirSync(src.dir);
+        }
+        catch {
+            lines.push(`--- ${src.dir} (directory not found) ---`);
+            continue;
+        }
+        // Only `.md` files can be injected (router SAFE_BASENAME_RE), so the catalog
+        // lists only those — a glob like `*.txt` simply yields nothing. Shared with
+        // preset detection via listMatchingMdFiles so the two never disagree.
+        const files = listMatchingMdFiles(entries, src.glob);
+        if (files.length === 0)
+            continue;
+        lines.push(`--- ${src.dir} ---`);
+        for (const f of files) {
+            lines.push(`${f}: ${extractDescription(join(src.dir, f))}`);
+        }
+        total += files.length;
+    }
+    lines.push(`(${total} entries)`);
+    lines.push("");
+    return lines.join("\n");
+}
 function listMemoryFiles(dir, prefix) {
     let entries = [];
     try {

package/dist/src/config.d.ts

@@ -11,6 +11,7 @@
  * try-boundaries on some paths). All YAML I/O is isolated in `loadYamlConfig`,
  * which swallows every error to null.
  */
+import { type CustomSource } from "./sources.js";
 export type ProviderType = "anthropic" | "openai" | "ollama";
 export interface MemhookConfig {
     enabled: boolean;
@@ -51,6 +52,38 @@ export interface MemhookConfig {
         path: string;
     };
     searchDirs: string[];
+    /**
+     * Whether to route memory the HOST already auto-loads at launch. Claude Code
+     * loads `~/.claude/rules/*.md` and `<cwd>/.claude/rules/*.md` in full at
+     * startup, so routing them again is positional re-surfacing, not new recall.
+     *
+     * OFF by default (the clean public behaviour): the catalog omits those
+     * host-autoloaded rule zones, so memhook routes only memory the host does NOT
+     * load (the `feedback_` / `project_` zones) — no double-injection. Measured: on
+     * a real 4.8k-prompt corpus, ~20% of injecting prompts re-injected a rule the
+     * host had already loaded in full (docs/private POC, 2026-06-02).
+     *
+     * Turn ON (`MEMHOOK_RESURFACE_HOST_LOADED=true`) for **long sessions / long
+     * context** — launch-loaded rules drift far from the current prompt, so
+     * re-surfacing the relevant ones near it restores their salience — or a
+     * **complex project that tolerates no drift**, where the redundant re-injection
+     * is a deliberate guard-rail.
+     */
+    resurfaceHostLoaded: boolean;
+    /**
+     * Extra memory sources beyond the built-in `~/.claude` zones — directories of
+     * `.md` files (any naming, via a glob) that memhook catalogs + routes like its
+     * own zones. This is how memhook cables onto memory that already exists in a
+     * project. YAML-only (`customSources:`), default empty. See `src/sources.ts`.
+     */
+    customSources: CustomSource[];
+    /**
+     * Enabled built-in host presets (e.g. `continue`, `cline`) — named bundles of
+     * sources for a known tool's `.md` convention, expanded against cwd/home at
+     * catalog/router time. YAML-only (`presets:`), default empty. All presets are
+     * experimental (doc-verified, not live-tested). See `src/sources.ts`.
+     */
+    presets: string[];
     logging: {
         jsonlPath: string;
     };
@@ -65,6 +98,19 @@ export interface MemhookConfig {
         thresholdFiles: number;
         cooldownDays: number;
     };
+    /**
+     * Optional proactive nudge: when a known host's memory directory exists in the
+     * project but no matching `presets:` entry routes it yet, the router attaches a
+     * one-line `systemMessage` suggesting `memhook presets detect`. Local-only (a
+     * readdir per preset dir, gated behind the cooldown), best-effort (never
+     * affects fail-soft), and always opt-in — it only points at the explicit
+     * `presets:` config, never auto-routes. See `maybePresetsNudge` in
+     * `src/router.ts`.
+     */
+    presetsNudge: {
+        enabled: boolean;
+        cooldownDays: number;
+    };
     scriptVersion: string;
 }
 export declare function loadConfig(env?: NodeJS.ProcessEnv): MemhookConfig;

package/dist/src/config.js

@@ -14,6 +14,7 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { loadYamlConfig } from "./configFile.js";
+import { resolveCustomSources, resolvePresetNames } from "./sources.js";
 import { MEMHOOK_VERSION } from "./version.js";
 /** Per-provider defaults applied once the provider type is known. */
 const PROVIDER_DEFAULTS = {
@@ -163,6 +164,9 @@ export function loadConfig(env = process.env) {
             str("MEMHOOK_PROJECTS_ROOT", yaml?.searchDirs?.projectsRoot, join(home, ".claude", "projects")),
             str("MEMHOOK_GLOBAL_RULES_DIR", yaml?.searchDirs?.globalRulesDir, join(home, ".claude", "rules")),
         ],
+        resurfaceHostLoaded: bool("MEMHOOK_RESURFACE_HOST_LOADED", yaml?.resurfaceHostLoaded, false),
+        customSources: resolveCustomSources(yaml?.customSources, home),
+        presets: resolvePresetNames(yaml?.presets),
         logging: {
             jsonlPath: str("MEMHOOK_LOG_PATH", yaml?.logging?.jsonlPath, join(home, ".claude", "logs", "memhook.log")),
         },
@@ -172,6 +176,10 @@ export function loadConfig(env = process.env) {
             thresholdFiles: num("MEMHOOK_CURATE_NUDGE_FILES", yaml?.curateNudge?.thresholdFiles, 250),
             cooldownDays: num("MEMHOOK_CURATE_NUDGE_COOLDOWN_DAYS", yaml?.curateNudge?.cooldownDays, 7),
         },
+        presetsNudge: {
+            enabled: bool("MEMHOOK_PRESETS_NUDGE", yaml?.presetsNudge?.enabled, true),
+            cooldownDays: num("MEMHOOK_PRESETS_NUDGE_COOLDOWN_DAYS", yaml?.presetsNudge?.cooldownDays, 7),
+        },
         scriptVersion: MEMHOOK_VERSION,
     };
 }

package/dist/src/configFile.d.ts

@@ -45,6 +45,11 @@ export interface RawConfigFile {
         projectsRoot?: string;
         globalRulesDir?: string;
     };
+    resurfaceHostLoaded?: boolean;
+    /** Extra `.md` source dirs; validated + narrowed by `resolveCustomSources`. */
+    customSources?: unknown;
+    /** Built-in host preset names; validated by `resolvePresetNames`. */
+    presets?: unknown;
     logging?: {
         jsonlPath?: string;
     };
@@ -54,6 +59,10 @@ export interface RawConfigFile {
         thresholdFiles?: number;
         cooldownDays?: number;
     };
+    presetsNudge?: {
+        enabled?: boolean;
+        cooldownDays?: number;
+    };
 }
 export declare function resolveConfigPath(env: NodeJS.ProcessEnv): string;
 export declare function loadYamlConfig(env: NodeJS.ProcessEnv): RawConfigFile | null;

package/dist/src/index.d.ts

@@ -7,8 +7,11 @@
  */
 export { loadConfig, type MemhookConfig, type ProviderType } from "./config.js";
 export { loadYamlConfig, resolveConfigPath, type RawConfigFile } from "./configFile.js";
-export { route, type HookInput, type HookOutput } from "./router.js";
+export { route, runHarness, type HookInput, type HookOutput } from "./router.js";
+export { claudeCodeAdapter } from "./adapters/claudeCode.js";
+export type { HarnessAdapter, HarnessInput, RouteResult } from "./adapters/types.js";
 export { buildCatalog, type CatalogBuildOptions } from "./catalog.js";
+export { resolveCustomSources, activeCustomSources, resolveSources, expandPresets, resolveActivePresetNames, resolvePresetNames, isPresetName, globToRegExp, expandHome, HOST_PRESETS, PRESET_NAMES, PRESET_AUTO, type CustomSource, type SourceScope, type PresetDef, } from "./sources.js";
 export { LocalCache, type CacheKeyInput } from "./cache.js";
 export { PreFilter } from "./preFilter.js";
 export { MEMHOOK_VERSION } from "./version.js";

package/dist/src/index.js

@@ -7,8 +7,10 @@
  */
 export { loadConfig } from "./config.js";
 export { loadYamlConfig, resolveConfigPath } from "./configFile.js";
-export { route } from "./router.js";
+export { route, runHarness } from "./router.js";
+export { claudeCodeAdapter } from "./adapters/claudeCode.js";
 export { buildCatalog } from "./catalog.js";
+export { resolveCustomSources, activeCustomSources, resolveSources, expandPresets, resolveActivePresetNames, resolvePresetNames, isPresetName, globToRegExp, expandHome, HOST_PRESETS, PRESET_NAMES, PRESET_AUTO, } from "./sources.js";
 export { LocalCache } from "./cache.js";
 export { PreFilter } from "./preFilter.js";
 export { MEMHOOK_VERSION } from "./version.js";

package/dist/src/presetsCmd.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `memhook presets list|detect` — discover the built-in per-host source presets
+ * so the user never has to know a preset's name or hand-write its paths.
+ *
+ *   list    Show every built-in preset (name, summary, the dirs/globs it points
+ *           at). Static — no disk access.
+ *   detect  Scan this project (cwd) + the home dir for the preset directories
+ *           that actually hold matching `.md` files, then print the YAML snippet
+ *           (`presets: [...]`) that enables the ones found.
+ *
+ * This is the I/O shell around the pure detector in `src/sources.ts`
+ * (`detectPresets`), the same functional-core / imperative-shell split as
+ * init.ts ↔ install.ts and skillsCmd.ts ↔ skills.ts. `presets` is NOT on the
+ * hook path, so it may exit non-zero on user error and use the TTY
+ * (docs/SPECIFICATION.md §9). The detector never throws (a missing/denied dir is
+ * recorded as absent), so detect/list always exit 0.
+ */
+export type PresetsSubcommand = "list" | "detect";
+export interface RunPresetsOptions {
+    subcommand: PresetsSubcommand;
+    /** Test seams. */
+    cwd?: string | undefined;
+    home?: string | undefined;
+    readDir?: ((dir: string) => string[]) | undefined;
+    env?: NodeJS.ProcessEnv | undefined;
+    out?: ((s: string) => void) | undefined;
+}
+export declare function runPresets(opts: RunPresetsOptions): number;