memhook 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,37 @@ 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.3.0](https://github.com/utilia-ai-wox/memhook/compare/v0.2.2...v0.3.0) (2026-06-02)
+
+
+### Features
+
+* add init/uninstall setup + tail live monitor ([#29](https://github.com/utilia-ai-wox/memhook/issues/29)) ([e895c9a](https://github.com/utilia-ai-wox/memhook/commit/e895c9a44fb46a141a20f1716999be3a0208bb89))
+
+
+### Bug Fixes
+
+* harden hook path against file-system races and stdin errors ([#30](https://github.com/utilia-ai-wox/memhook/issues/30)) ([8a0f10e](https://github.com/utilia-ai-wox/memhook/commit/8a0f10e1d7a7184b7cc5fdcb4eb20ae4be516b0d))
+
+
+### Documentation
+
+* refresh all docs for v0.2.2 and revamp the README ([#27](https://github.com/utilia-ai-wox/memhook/issues/27)) ([ad1106a](https://github.com/utilia-ai-wox/memhook/commit/ad1106a3a0cea47ce75201a781fdf5eda80324b2))
+
+## [0.2.2](https://github.com/utilia-ai-wox/memhook/compare/v0.2.1...v0.2.2) (2026-06-02)
+
+
+### Bug Fixes
+
+* **ci:** use npm install in publish job (repo ships no lockfile) ([#25](https://github.com/utilia-ai-wox/memhook/issues/25)) ([b12f873](https://github.com/utilia-ai-wox/memhook/commit/b12f873c2a83c9656134910a2971117687992f1e))
+
+## [0.2.1](https://github.com/utilia-ai-wox/memhook/compare/v0.2.0...v0.2.1) (2026-06-02)
+
+
+### Bug Fixes
+
+* clean dist before build to avoid shipping stale artifacts ([#23](https://github.com/utilia-ai-wox/memhook/issues/23)) ([e34e7ad](https://github.com/utilia-ai-wox/memhook/commit/e34e7ad08688f7d687dd2e42ebe62b52bbbac660))
+
 ## [0.2.0](https://github.com/utilia-ai-wox/memhook/compare/v0.1.0-preview.0...v0.2.0) (2026-06-02)
 
 
@@ -31,75 +62,9 @@ and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.
 
 * 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
+## [0.1.0-preview.0](https://github.com/utilia-ai-wox/memhook/releases/tag/v0.1.0-preview.0) (2026-05-28)
+
+Initial public preview: Anthropic Haiku provider, fail-soft pipeline, cap-A1
+projection fix, JSONL observability log, catalog builder, local LRU cache,
+trivial-prompt pre-filter, and the `memhook run | build-catalog | version`
+CLI.

package/README.md

@@ -1,91 +1,128 @@
+<div align="center">
+
 # memhook
 
-> Semantic memory router for Claude Code — picks the relevant feedbacks &
-> rules for each prompt via Haiku, injects them as `additionalContext`.
+**Stop loading every memory file on every prompt. memhook routes only the relevant ones.**
 
-**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`.
+<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>
+  <a href="https://www.npmjs.com/package/memhook"><img src="https://img.shields.io/npm/dm/memhook?color=cb3837" alt="npm downloads"></a>
+  <a href="https://github.com/utilia-ai-wox/memhook/actions/workflows/ci.yml"><img src="https://github.com/utilia-ai-wox/memhook/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/utilia-ai-wox/memhook/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/memhook?color=blue" alt="License: MIT"></a>
+  <img src="https://img.shields.io/node/v/memhook" alt="Node version">
+  <a href="https://github.com/utilia-ai-wox/memhook/stargazers"><img src="https://img.shields.io/github/stars/utilia-ai-wox/memhook?style=social" alt="GitHub stars"></a>
+</p>
 
-## Why
+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`.
 
-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).
+</div>
 
-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.
+<!-- TODO(demo): record an asciinema of `tail -f ~/.claude/logs/memhook.log`
+     while prompting Claude Code — it shows the router picking files live.
+     Embed: [![asciicast](https://asciinema.org/a/XXXXX.svg)](https://asciinema.org/a/XXXXX) -->
 
-## How it works
+## ✨ Features
 
-```
-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              │
-└────────────────────────────────────────┘
-```
+- 🎯 **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.
+- 🛡️ **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.
+- 🤫 **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.
+- 🧰 **One-command setup** — `memhook init` wires the hooks (with backup); `memhook tail` shows routing live.
 
-## Install
+## 🤔 Why
 
-```bash
-npm install -g memhook      # not yet published — see "From source" below
-```
+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.
+
+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.
 
-### From source (preview)
+| Approach              | Tokens / prompt | Relevance         |
+| --------------------- | --------------- | ----------------- |
+| Load all memory files | 10–14k          | mostly irrelevant |
+| **memhook**           | ~2k             | only what matches |
+
+## 🚀 Quick start
 
 ```bash
-git clone https://github.com/utilia-ai-wox/memhook.git
-cd memhook
-bun install
-bun run build
-npm link
+npm install -g memhook
+export ANTHROPIC_API_KEY=sk-ant-…   # or see Providers for OpenAI / Ollama
+memhook init
 ```
 
-## Setup
+`memhook init` detects your Claude Code config, wires the two hooks into
+`~/.claude/settings.json` (backing it up first, never clobbering existing
+hooks), and builds the initial catalog. It is idempotent and supports
+`--dry-run`. Restart Claude Code and you're done — then watch it work live
+with [`memhook tail`](#-observability).
 
-1. **Set your API key**
-
-   ```bash
-   export ANTHROPIC_API_KEY=sk-ant-…
-   ```
+<details>
+<summary>Manual setup (what <code>init</code> automates)</summary>
 
-2. **Build the initial catalog**
+1. **Build the initial catalog**
 
    ```bash
    memhook build-catalog
    # → ~/.claude/cache/memory-catalog.txt
    ```
 
-3. **Wire the hooks** in `~/.claude/settings.json`:
+2. **Wire the hooks** in `~/.claude/settings.json`:
 
    ```json
    {
      "hooks": {
        "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "memhook run" }] }],
-       "SessionStart": [
-         {
-           "hooks": [{ "type": "command", "command": "memhook build-catalog" }]
-         }
-       ]
+       "SessionStart": [{ "hooks": [{ "type": "command", "command": "memhook build-catalog" }] }]
      }
    }
    ```
 
-## Configuration
+Remove it all later with `memhook uninstall` (also backs up first).
+
+</details>
 
-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.
+<details>
+<summary>From source (for contributors)</summary>
+
+```bash
+git clone https://github.com/utilia-ai-wox/memhook.git
+cd memhook
+bun install
+bun run build
+npm link
+```
+
+</details>
+
+## 🔍 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 the router with catalog        │ ── 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              │
+└────────────────────────────────────────┘
+```
+
+## ⚙️ Configuration
+
+Every knob is an env var, and 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                                |
 | -------------------------------- | ------------------------------- | -------------------------------------- |
@@ -119,7 +156,7 @@ selection:
   maxFiles: 5
 ```
 
-## Providers
+## 🔌 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
@@ -141,7 +178,7 @@ LLM endpoint _you_ choose to route through.
   the native `/api/chat` endpoint with `stream:false`; the timeout defaults to
   30s to absorb cold model loads.
 
-## Observability
+## 📊 Observability
 
 Every invocation appends one JSON line to `~/.claude/logs/memhook.log`:
 
@@ -157,18 +194,34 @@ Every invocation appends one JSON line to `~/.claude/logs/memhook.log`:
   "cache_read": 13398,
   "additional_size_chars": 20225,
   "additional_size_tokens_est": 5056,
-  "status": "ok"
+  "status": "ok",
+  "model": "claude-haiku-4-5"
 }
 ```
 
-Useful one-liner to inspect the last 7 days:
+### Live view — `memhook tail`
+
+Watch routing decisions as they happen, in colour:
+
+```bash
+memhook tail                          # follow live (Ctrl-C to quit)
+memhook tail --no-follow              # print recent log + summary, then exit
+memhook tail --status ok,cache_hit    # filter by status
+memhook tail -n 50                    # show more history first
+```
+
+Each row shows the time, status, prompt preview, latency, and model, plus the
+memories that were injected; a summary line reports the cache-hit rate and
+p50/p95 latency. Colour degrades to plain text when piped or under `NO_COLOR`.
+`tail` only reads the log, so it can never affect the hook. For raw analysis,
+the log is plain JSONL — e.g. the last 7 days by status:
 
 ```bash
 jq -c 'select((.ts | fromdateiso8601) > (now - 7*86400)) | .status' \
   ~/.claude/logs/memhook.log | sort | uniq -c
 ```
 
-## Status values
+### Status values
 
 | `status`               | Meaning                                               |
 | ---------------------- | ----------------------------------------------------- |
@@ -184,20 +237,29 @@ jq -c 'select((.ts | fromdateiso8601) > (now - 7*86400)) | .status' \
 | `api_no_content`       | API returned 200 but no text                          |
 | `parse_invalid`        | Response wasn't a valid JSON array                    |
 
-## Fail-soft
+## 🛡️ 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.
+`additionalContext` and logs the status. **Your prompt always reaches the
+model**, just without injected memories for that turn.
 
-## Roadmap
+## 🗺️ Roadmap
 
-- `v0.2` ✅ — YAML config file, OpenAI provider, Ollama local provider
-- `v0.3` — TUI live monitor (`memhook tail`)
+- `v0.2` ✅ — YAML config file, OpenAI provider, Ollama local provider (published on npm)
+- `v0.3` — `memhook init` / `memhook uninstall` setup wizard + zero-dep 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
+- `v1.0` — API frozen, cross-platform validated, listed on awesome-lists
+
+## 🤝 Contributing
+
+Contributions welcome — please read [CONTRIBUTING.md](CONTRIBUTING.md) first.
+The hook contract (fail-soft, no telemetry, strict TypeScript) is
+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.
 
 ## License
 

package/dist/bin/memhook.d.ts

@@ -1,16 +1,21 @@
 #!/usr/bin/env node
 /**
- * memhook CLI — three commands shipped in v0.1 preview:
+ * memhook CLI.
  *
  *   memhook run            Read stdin (Claude Code hook JSON), write hook output
  *   memhook build-catalog  Rebuild ~/.claude/cache/memory-catalog.txt
+ *   memhook init           Wire memhook into ~/.claude/settings.json (interactive)
+ *   memhook uninstall      Remove memhook's hooks from ~/.claude/settings.json
+ *   memhook tail           Pretty live view of the JSONL routing log
  *   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" }] }]
+ * Only `run` obeys the fail-soft hook contract (never throws, never exits
+ * non-zero). The interactive commands (`init`/`uninstall`/`tail`) may exit
+ * non-zero on user error and are free to use the TTY — docs/SPECIFICATION.md §9.
+ *
+ * Wired into ~/.claude/settings.json hooks (see `memhook init`):
+ *   "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

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