memhook 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,105 @@
+# Changelog
+
+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.2.0](https://github.com/utilia-ai-wox/memhook/compare/v0.1.0-preview.0...v0.2.0) (2026-06-02)
+
+
+### Features
+
+* **providers:** add multi-provider support and optional YAML config ([97920e4](https://github.com/utilia-ai-wox/memhook/commit/97920e4dc5680dd403336b0a9c44a021fe193de3))
+* **providers:** add OpenAI and Ollama providers + optional YAML config ([8bc5555](https://github.com/utilia-ai-wox/memhook/commit/8bc5555ad73130267984b0d18660a630fdb409d3))
+
+
+### Bug Fixes
+
+* **config:** clamp numeric knobs and widen boolean env vocabulary ([0ad7c6f](https://github.com/utilia-ai-wox/memhook/commit/0ad7c6f13ada7c33933fd8ef70fdf20d35e1f882))
+* **config:** clamp numeric knobs and widen boolean env vocabulary ([ea386c0](https://github.com/utilia-ai-wox/memhook/commit/ea386c0247fc8746908635d0362cff3f01b34be2))
+* point package exports at the compiled dist/src layout ([970ee71](https://github.com/utilia-ai-wox/memhook/commit/970ee711685baaaf63967afb8c5d696a9688486b))
+* point package exports at the compiled dist/src layout ([57e1ff4](https://github.com/utilia-ai-wox/memhook/commit/57e1ff469e4eeb25cbca568f9a390cac690c759a))
+
+
+### Documentation
+
+* document v0.2 multi-provider and YAML config ([63e6d1b](https://github.com/utilia-ai-wox/memhook/commit/63e6d1b709f2f405b1f18c18958fe28979d57702))
+
+
+### Chore
+
+* graduate release line to clean 0.2.0 ([f0a07e5](https://github.com/utilia-ai-wox/memhook/commit/f0a07e51fe5792df4efd7af9d59452d97603b675))
+
+## [Unreleased]
+
+### Added
+
+- **OpenAI provider** (`MEMHOOK_PROVIDER=openai`) — Chat Completions API,
+  `Authorization: Bearer`, catalog as the leading system message so OpenAI's
+  automatic prompt caching can engage. Default model `gpt-4o-mini`.
+- **Ollama local provider** (`MEMHOOK_PROVIDER=ollama`) — native `/api/chat`
+  endpoint, no API key, `stream:false` + `format:"json"`. Default model
+  `llama3.1`, with a 30s default timeout to absorb cold model loads.
+- **YAML config file** (`config.yaml`) — optional, opt-in, read from
+  `$MEMHOOK_CONFIG` or `~/.config/memhook/config.yaml`. Precedence is
+  env var > YAML > default. A missing or malformed file is ignored
+  (fail-soft to defaults). See `config.example.yaml`.
+- `src/providers/factory.ts` — `createProvider()` selects the adapter from
+  `config.provider.type` with compile-time exhaustiveness.
+- `src/providers/http.ts` — single shared `postJsonWithRetry` transport
+  (timeout + single retry) used by all providers.
+- `MEMHOOK_PROVIDER` and `MEMHOOK_CONFIG` env vars; per-provider defaults for
+  model / API-key env var / timeout.
+- Hardening pre-publish (CI, CHANGELOG, CONTRIBUTING, `.env.example`)
+
+### Changed
+
+- The provider interface is now provider-agnostic: Anthropic-specific
+  `betaHeaders` and `cacheControlTtl` moved off the shared `SelectionRequest`
+  into `AnthropicProviderOptions`. `ProviderConfig.apiKey` is now optional
+  (local providers need none).
+- Cache key now includes the provider identity (`type:model`) so switching
+  provider or model never serves a selection made by a different model.
+- The two hardcoded version strings (`config.ts`, `bin/memhook.ts`) are
+  centralised in `src/version.ts`.
+
+### Note
+
+- Adding `openai` / `ollama` introduces opt-in outbound calls to
+  `api.openai.com` / `localhost:11434`. The default remains Anthropic-only;
+  `api.anthropic.com` is still the sole endpoint for an unconfigured user. No
+  telemetry, no phone-home.
+- First runtime dependency: `yaml` (zero sub-dependencies).
+
+## [0.1.0-preview.0] — 2026-05-28
+
+Initial public preview.
+
+### Added
+
+- `src/router.ts` — UserPromptSubmit hook entry point with cap-A1 projection
+  fix (skip a file pre-injection if its content would push the cumulated
+  injection past `maxAdditionalChars`, while always allowing at least one).
+- `src/catalog.ts` — catalog builder with Q4 title-only reduction for
+  non-CWD zones (~50% size cut on a typical 3-repo layout).
+- `src/cache.ts` — local LRU cache keyed on
+  `sha256(prompt + catalog_mtime + cwd + script_version)`. Stored as
+  per-key JSON files. 60-min TTL by default, 7-day eviction floor.
+- `src/preFilter.ts` — trivial-prompt pre-filter loaded from
+  `~/.config/memhook/trivial-words.txt` with a sensible default list.
+- `src/providers/anthropic.ts` — provider implementation for Anthropic
+  Messages API. Uses `ephemeral` `1h` cache control on the system prompt
+  (GA in 2026, no beta header) so the catalog sits in cache (10× cheaper
+  writes amortised across the hour).
+- `src/config.ts` — env-driven config loader. No YAML in v0.1; deferred to
+  v0.2.
+- `bin/memhook.ts` — CLI with `run`, `build-catalog`, `version`, `help`.
+- JSONL observability log at `~/.claude/logs/memhook.log` including
+  `additional_size_chars` + `additional_size_tokens_est` so users can audit
+  the actual size of the injected `additionalContext` over time.
+- 18 unit tests covering the router pipeline, pre-filter normalisation, and
+  cache key derivation / TTL / eviction.
+
+[Unreleased]: https://github.com/utilia-ai-wox/memhook/compare/v0.1.0-preview.0...HEAD
+[0.1.0-preview.0]: https://github.com/utilia-ai-wox/memhook/releases/tag/v0.1.0-preview.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,204 @@
+# memhook
+
+> Semantic memory router for Claude Code — picks the relevant feedbacks &
+> rules for each prompt via Haiku, injects them as `additionalContext`.
+
+**Status**: `v0.1.0-preview` — extracted from a private hook used daily across
+3 large repos. API surface and naming may shift before `v1.0.0`.
+
+## Why
+
+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 (10–14k tokens of
+catalog overhead, most of it irrelevant to the current question).
+
+memhook uses **Haiku 4.5** as a cheap router: each user prompt is matched
+against a one-line catalog of all available memory files, and only the 0–5
+most relevant ones are read and injected into `additionalContext`. The rest
+sit on disk, invisible to Claude until they matter.
+
+## How it works
+
+```
+UserPromptSubmit hook
+    │
+    ▼
+┌────────────────────────────────────────┐
+│ 1. Pre-filter trivial prompts          │ ── "ok" / "merci" → skip LLM
+│ 2. Check local LRU cache               │ ── identical prompt < 60min → hit
+│ 3. Call Haiku with catalog as system   │ ── ephemeral 1h cache control
+│ 4. Parse JSON array of basenames       │ ── ["feedback_X.md", "rule_Y.md"]
+│ 5. Read files, cap by token budget     │ ── max 9.5k chars or 5 files
+│ 6. Emit additionalContext              │
+└────────────────────────────────────────┘
+```
+
+## Install
+
+```bash
+npm install -g memhook      # not yet published — see "From source" below
+```
+
+### From source (preview)
+
+```bash
+git clone https://github.com/utilia-ai-wox/memhook.git
+cd memhook
+bun install
+bun run build
+npm link
+```
+
+## Setup
+
+1. **Set your API key**
+
+   ```bash
+   export ANTHROPIC_API_KEY=sk-ant-…
+   ```
+
+2. **Build the initial catalog**
+
+   ```bash
+   memhook build-catalog
+   # → ~/.claude/cache/memory-catalog.txt
+   ```
+
+3. **Wire the hooks** in `~/.claude/settings.json`:
+
+   ```json
+   {
+     "hooks": {
+       "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "memhook run" }] }],
+       "SessionStart": [
+         {
+           "hooks": [{ "type": "command", "command": "memhook build-catalog" }]
+         }
+       ]
+     }
+   }
+   ```
+
+## Configuration
+
+Every knob is an env var, and (since `v0.2`) optionally a YAML file.
+Precedence per key is **env var > YAML file > built-in default**, so an
+env-var-only setup behaves exactly as before. Sensible defaults work for most
+users.
+
+| Variable                         | Default                         | Purpose                                |
+| -------------------------------- | ------------------------------- | -------------------------------------- |
+| `MEMHOOK_ENABLED`                | `true`                          | Master toggle                          |
+| `MEMHOOK_PROVIDER`               | `anthropic`                     | `anthropic` \| `openai` \| `ollama`    |
+| `MEMHOOK_MODEL`                  | per-provider                    | Model id (provider default if unset)   |
+| `MEMHOOK_API_KEY_ENV`            | per-provider                    | Name of env var holding the API key    |
+| `MEMHOOK_BASE_URL`               | per-provider                    | Override the provider API endpoint     |
+| `MEMHOOK_CONFIG`                 | `~/.config/memhook/config.yaml` | Path to the optional YAML config file  |
+| `MEMHOOK_MAX_FILES`              | `5`                             | Hard cap on injected files             |
+| `MEMHOOK_MAX_ADDITIONAL_CHARS`   | `9500`                          | Soft cap on injected chars (≈2.4k tok) |
+| `MEMHOOK_MAX_OUTPUT_TOKENS`      | `200`                           | Model output cap for the selection     |
+| `MEMHOOK_TIMEOUT_MS`             | `8000` (`30000` for ollama)     | Per-request timeout                    |
+| `MEMHOOK_DISABLE_CACHE=true`     | _(off)_                         | Skip local LRU cache                   |
+| `MEMHOOK_DISABLE_PREFILTER=true` | _(off)_                         | Skip trivial-prompt skip               |
+| `MEMHOOK_DEBUG=true`             | _(off)_                         | Print errors to stderr                 |
+
+### YAML config (optional)
+
+memhook works with **no config file at all**. If you prefer YAML, copy
+[`config.example.yaml`](config.example.yaml) to `~/.config/memhook/config.yaml`
+(or point `MEMHOOK_CONFIG` at it). A missing or malformed file is ignored
+silently — memhook falls back to env vars and defaults, never blocking your
+prompt.
+
+```yaml
+provider:
+  type: openai
+  # model + apiKeyEnv default to gpt-4o-mini + OPENAI_API_KEY
+selection:
+  maxFiles: 5
+```
+
+## Providers
+
+The default provider is **Anthropic** — with no `MEMHOOK_PROVIDER` set, the
+only outbound call memhook ever makes is to `api.anthropic.com`, using your own
+key. Selecting another provider is **opt-in** and changes which endpoint is
+contacted. memhook never phones home and has no telemetry; "provider" means the
+LLM endpoint _you_ choose to route through.
+
+| Provider  | `MEMHOOK_PROVIDER` | Default model      | API key             | Endpoint                                |
+| --------- | ------------------ | ------------------ | ------------------- | --------------------------------------- |
+| Anthropic | `anthropic`        | `claude-haiku-4-5` | `ANTHROPIC_API_KEY` | `api.anthropic.com`                     |
+| OpenAI    | `openai`           | `gpt-4o-mini`      | `OPENAI_API_KEY`    | `api.openai.com`                        |
+| Ollama    | `ollama`           | `llama3.1`         | _none_ (local)      | `http://localhost:11434` (configurable) |
+
+- **OpenAI** — set `MEMHOOK_PROVIDER=openai` and `OPENAI_API_KEY`. Uses the
+  Chat Completions API; the catalog rides as the leading system message so
+  OpenAI's automatic prompt caching can engage on a large catalog.
+- **Ollama** — set `MEMHOOK_PROVIDER=ollama` and make sure the model is pulled
+  (`ollama pull llama3.1`) with the daemon running. No API key required. Hits
+  the native `/api/chat` endpoint with `stream:false`; the timeout defaults to
+  30s to absorb cold model loads.
+
+## Observability
+
+Every invocation appends one JSON line to `~/.claude/logs/memhook.log`:
+
+```json
+{
+  "ts": "2026-05-28T08:41:18Z",
+  "prompt_preview": "fix the OPAQUE wire format drift…",
+  "selected": ["opaque-interop-rust-ts.md"],
+  "latency_ms": 1727,
+  "tokens_in": 12,
+  "tokens_out": 28,
+  "cache_create": 0,
+  "cache_read": 13398,
+  "additional_size_chars": 20225,
+  "additional_size_tokens_est": 5056,
+  "status": "ok"
+}
+```
+
+Useful one-liner to inspect the last 7 days:
+
+```bash
+jq -c 'select((.ts | fromdateiso8601) > (now - 7*86400)) | .status' \
+  ~/.claude/logs/memhook.log | sort | uniq -c
+```
+
+## Status values
+
+| `status`               | Meaning                                               |
+| ---------------------- | ----------------------------------------------------- |
+| `ok`                   | Files injected from a fresh model selection           |
+| `cache_hit`            | Files injected from local LRU cache                   |
+| `pre_filter_skip`      | Trivial prompt, LLM call skipped                      |
+| `empty_selection`      | The model returned `[]` (no memory needed)            |
+| `all_unfound`          | The model returned basenames that don't exist on disk |
+| `no_catalog`           | Catalog missing — run `memhook build-catalog`         |
+| `no_api_key`           | API key env var not set (not needed for ollama)       |
+| `provider_init_failed` | Provider couldn't be constructed (bad config)         |
+| `api_no_response`      | Network error or timeout                              |
+| `api_no_content`       | API returned 200 but no text                          |
+| `parse_invalid`        | Response wasn't a valid JSON array                    |
+
+## Fail-soft
+
+memhook never blocks Claude Code. On any error — missing key, network
+timeout, malformed JSON, broken filesystem — it emits an empty
+`additionalContext` and logs the status. Your prompt always reaches the
+model, just without injected memories for that turn.
+
+## Roadmap
+
+- `v0.2` ✅ — YAML config file, OpenAI provider, Ollama local provider
+- `v0.3` — TUI live monitor (`memhook tail`)
+- `v0.4` — Companion skills (`/wrap`, `/curate`, `/relay`)
+- `v0.5` — Auto-bootstrap (`memhook init` detects empty memory dirs)
+- `v1.0` — Cross-platform validated, published to npm
+
+## License
+
+MIT © wox

package/dist/bin/memhook.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * memhook CLI — three commands shipped in v0.1 preview:
+ *
+ *   memhook run            Read stdin (Claude Code hook JSON), write hook output
+ *   memhook build-catalog  Rebuild ~/.claude/cache/memory-catalog.txt
+ *   memhook version        Print package version
+ *
+ * Designed to be wired into ~/.claude/settings.json hooks:
+ *   "UserPromptSubmit": [{ "hooks": [{ "type": "command",
+ *                                      "command": "memhook run" }] }]
+ *   "SessionStart":     [{ "hooks": [{ "type": "command",
+ *                                      "command": "memhook build-catalog" }] }]
+ */
+export {};
+//# sourceMappingURL=memhook.d.ts.map

package/dist/bin/memhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memhook.d.ts","sourceRoot":"","sources":["../../bin/memhook.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;GAYG"}

package/dist/bin/memhook.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+/**
+ * memhook CLI — three commands shipped in v0.1 preview:
+ *
+ *   memhook run            Read stdin (Claude Code hook JSON), write hook output
+ *   memhook build-catalog  Rebuild ~/.claude/cache/memory-catalog.txt
+ *   memhook version        Print package version
+ *
+ * Designed to be wired into ~/.claude/settings.json hooks:
+ *   "UserPromptSubmit": [{ "hooks": [{ "type": "command",
+ *                                      "command": "memhook run" }] }]
+ *   "SessionStart":     [{ "hooks": [{ "type": "command",
+ *                                      "command": "memhook build-catalog" }] }]
+ */
+import { route } from "../src/router.js";
+import { buildCatalog } from "../src/catalog.js";
+import { loadConfig } from "../src/config.js";
+import { MEMHOOK_VERSION as VERSION } from "../src/version.js";
+async function main() {
+    const cmd = process.argv[2] ?? "help";
+    switch (cmd) {
+        case "run":
+            await cmdRun();
+            break;
+        case "build-catalog":
+            cmdBuildCatalog();
+            break;
+        case "version":
+        case "--version":
+        case "-v":
+            console.log(VERSION);
+            break;
+        case "help":
+        case "--help":
+        case "-h":
+            printHelp();
+            break;
+        default:
+            console.error(`memhook: unknown command "${cmd}"`);
+            printHelp();
+            process.exit(1);
+    }
+}
+async function cmdRun() {
+    const stdin = await readStdin();
+    let output;
+    try {
+        output = await route(stdin);
+    }
+    catch (err) {
+        // Fail-soft: emit empty additionalContext, never block the user prompt
+        output = {
+            hookSpecificOutput: {
+                hookEventName: "UserPromptSubmit",
+                additionalContext: "",
+            },
+        };
+        if (process.env["MEMHOOK_DEBUG"] === "true") {
+            process.stderr.write(`memhook run error: ${String(err)}\n`);
+        }
+    }
+    process.stdout.write(JSON.stringify(output) + "\n");
+}
+function cmdBuildCatalog() {
+    const config = loadConfig();
+    const result = buildCatalog({
+        cwd: process.cwd(),
+        outputPath: config.catalog.path,
+    });
+    process.stderr.write(`[memhook build-catalog] ${config.catalog.path} — ${result.lines}L, ${result.bytes}B\n`);
+}
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (chunk) => (data += chunk));
+        process.stdin.on("end", () => resolve(data));
+        process.stdin.on("error", reject);
+    });
+}
+function printHelp() {
+    console.log(`memhook ${VERSION}
+
+USAGE
+  memhook <command>
+
+COMMANDS
+  run                Read Claude Code hook JSON from stdin, emit additionalContext
+  build-catalog      Rebuild the memory catalog at $MEMHOOK_CATALOG_PATH
+  version            Print version
+  help               Show this message
+
+ENV VARS
+  MEMHOOK_ENABLED                 toggle (default: true)
+  MEMHOOK_PROVIDER                anthropic | openai | ollama (default: anthropic)
+  MEMHOOK_MODEL                   model id (per-provider default if unset)
+  MEMHOOK_API_KEY_ENV             env var name holding the API key
+                                  (anthropic: ANTHROPIC_API_KEY, openai: OPENAI_API_KEY,
+                                   ollama: none required)
+  MEMHOOK_BASE_URL                override the provider API endpoint
+  MEMHOOK_CONFIG                  path to a YAML config file
+                                  (default: ~/.config/memhook/config.yaml)
+  MEMHOOK_MAX_FILES               file-count cap (default: 5)
+  MEMHOOK_MAX_ADDITIONAL_CHARS    injection size cap (default: 9500)
+  MEMHOOK_MAX_OUTPUT_TOKENS       model output cap (default: 200)
+  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_DEBUG=true              print errors to stderr (default: silent fail-soft)
+
+PROVIDERS
+  Default is Anthropic (only api.anthropic.com is contacted). Selecting
+  openai or ollama is opt-in and changes the outbound endpoint to
+  api.openai.com or your local Ollama (http://localhost:11434) respectively.
+  Per-key precedence is env var > YAML config > built-in default.
+`);
+}
+main().catch((err) => {
+    process.stderr.write(`memhook fatal: ${String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=memhook.js.map

package/dist/bin/memhook.js.map

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

package/dist/src/cache.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Local LRU cache for memhook selections.
+ *
+ * Key = sha256(prompt + catalog_mtime + cwd + script_version + provider). Bump
+ * any of these and the entry is automatically invalidated — `provider`
+ * (type + model) is included so switching provider/model never serves a stale
+ * selection made by a different model.
+ *
+ * Storage: one JSON file per key under config.cache.dir. TTL enforced via
+ * filesystem mtime check.
+ */
+export interface CacheKeyInput {
+    prompt: string;
+    catalogMtimeMs: number;
+    cwd: string;
+    scriptVersion: string;
+    /** Provider identity, e.g. "anthropic:claude-haiku-4-5". */
+    provider: string;
+}
+export declare class LocalCache {
+    private readonly dir;
+    private readonly ttlMin;
+    private readonly evictionDays;
+    constructor(dir: string, ttlMin: number, evictionDays: number);
+    key(input: CacheKeyInput): string;
+    get(key: string): string | null;
+    put(key: string, value: string): void;
+    evictStale(): number;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/src/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,UAAU;IAEnB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,YAAY;gBAFZ,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM;IAKvC,GAAG,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM;IAKjC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAiB/B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAKrC,UAAU,IAAI,MAAM;CAwBrB"}

package/dist/src/cache.js

@@ -0,0 +1,80 @@
+/**
+ * Local LRU cache for memhook selections.
+ *
+ * Key = sha256(prompt + catalog_mtime + cwd + script_version + provider). Bump
+ * any of these and the entry is automatically invalidated — `provider`
+ * (type + model) is included so switching provider/model never serves a stale
+ * selection made by a different model.
+ *
+ * Storage: one JSON file per key under config.cache.dir. TTL enforced via
+ * filesystem mtime check.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export class LocalCache {
+    dir;
+    ttlMin;
+    evictionDays;
+    constructor(dir, ttlMin, evictionDays) {
+        this.dir = dir;
+        this.ttlMin = ttlMin;
+        this.evictionDays = evictionDays;
+        mkdirSync(this.dir, { recursive: true });
+    }
+    key(input) {
+        const raw = `${input.prompt}|${input.catalogMtimeMs}|${input.cwd}|${input.scriptVersion}|${input.provider}`;
+        return createHash("sha256").update(raw).digest("hex");
+    }
+    get(key) {
+        const file = join(this.dir, `${key}.json`);
+        let stat;
+        try {
+            stat = statSync(file);
+        }
+        catch {
+            return null;
+        }
+        const ageMs = Date.now() - stat.mtimeMs;
+        if (ageMs > this.ttlMin * 60_000)
+            return null;
+        try {
+            return readFileSync(file, "utf8");
+        }
+        catch {
+            return null;
+        }
+    }
+    put(key, value) {
+        const file = join(this.dir, `${key}.json`);
+        writeFileSync(file, value, "utf8");
+    }
+    evictStale() {
+        let removed = 0;
+        const cutoffMs = Date.now() - this.evictionDays * 86_400_000;
+        let entries = [];
+        try {
+            entries = readdirSync(this.dir);
+        }
+        catch {
+            return 0;
+        }
+        for (const name of entries) {
+            if (!name.endsWith(".json"))
+                continue;
+            const file = join(this.dir, name);
+            try {
+                const stat = statSync(file);
+                if (stat.mtimeMs < cutoffMs) {
+                    unlinkSync(file);
+                    removed++;
+                }
+            }
+            catch {
+                // ignore
+            }
+        }
+        return removed;
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/src/cache.js.map

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

package/dist/src/catalog.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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/`.
+ *
+ * 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.
+ */
+export interface CatalogBuildOptions {
+    cwd: string;
+    projectsRoot?: string;
+    globalRulesDir?: string;
+    outputPath: string;
+}
+export declare function buildCatalog(opts: CatalogBuildOptions): {
+    lines: number;
+    bytes: number;
+};
+//# sourceMappingURL=catalog.d.ts.map

package/dist/src/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAaH,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB;AAQD,wBAAgB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf,CA2BA"}