Equip Claude Code with persistent memory and multi-agent review

claude-hooks

Cross-platform Claude Code hooks that auto-recall from Qdrant + Memory KG
on every prompt and write findings back at the end of the turn.

Install once at the user level and every Claude Code session gets
deterministic memory recall + storage - no per-project init, no model
forgetting. Beyond the core:

• v0.5+ - transparent api.anthropic.com proxy with stats DB +
  dashboard + behavior canaries
• v0.6+ - in-process Python AST code-graph (with optional
  tree-sitter / MCP-server / clustering extras)
• v0.7+ - session-scoped LSP engine + opt-in ruff PostToolUse hook
• v0.8+ - Caliber grounding proxy + shared agent_loop.runner
• v1.0 - daemon-first hook execution, stable skill surface,
  pgvector backup + validity canary stack
• v1.1 - two LLM-to-LLM advisory features built on
  agent_loop.runner:
  • /get-advice - single-model second-opinion advisor talking
    to a configured Ollama backend with project-grounded tool
    access. Multi-turn, effort-budgeted, tool-filtered.
    See docs/get-advice.md.
  • /consultants - multi-agent council (planner →
    researcher → critic → synthesizer) with full per-role
    LLM-message-history persistence in transcript.db, so a
    follow-up against a session reopened from disk produces an
    answer indistinguishable from a still-warm one. Every role can
    call tools, not just the researcher - so the critic verifies a
    path:line instead of taking the researcher's word for it, and
    reports a CORRECTIONS: block when the two disagree. Measured
    cheaper and more accurate than the researcher-only surface
    (−30% prompt tokens, and 100% vs 0% detection of false research
    claims - see
    benchmarks/consultants/results/2026-08-01/). Multi-model
    fan-out at xmedium/xhigh/xmax effort tiers, multi-critic
    consensus with meta-critic combine at xmax, synthesizer
    failure-fallback model chain, and a degraded-answer composer
    that surfaces the researcher + critic work even when the
    synthesizer can't compose. See
    docs/consultants.md for the runbook,
    docs/consultants-roles.md for the
    role-by-role reference (all 6 active roles, including the
    opt-in tool_executor + coder), and
    the benchmark index for the cloud-model
    evaluation suite (council-role sweeps, coder, per-language
    incl. the coder_easy bank - 30 problems × 6 languages = 180
    questions emitted by benchmarks/consultants/gen_coder_easy.py,
    graded through benchmarks/consultants/oracles_mlang.py -
    tool-executor, stall, and caliber-eval - each with its grading
    protocol).
• v1.2 - caliber-grounding-proxy cloud-resilience port +
  in-repo caliber-eval cohort at
  docs/caliber-eval-results/. Verdict:
  claude-cli stays the default for caliber init, glm-5.1:cloud
  is the recommended non-claude-cli fallback.
• v1.3 - collapses the per-verb slash-command skills into two
  dispatcher skills: /get-advice <verb> (verbs:
  ask/model/effort/tools) and /consultants <verb> (verbs:
  ask/followup/list/show/config) with implicit ask
  default. Cuts the upfront slash-command menu cost from 9 entries
  to 2.
• v1.4 - adds mozilla-ai/llamafile as a fallback-capable
  embedding engine for the pgvector + sqlite_vec providers,
  supervised by the daemon (spawn-on-demand, 5-min idle reap).
  Installer learns embedder dialogs for sqlite_vec and validate-only
  connectivity reports for qdrant/memory-kg. See
  docs/llamafile-integration.md.
• v1.5 - extends the llamafile integration to the
  chat-completion side: HyDE / reflect / consolidate /
  get-advice / consultants / caliber-grounding-proxy can route to
  a daemon-supervised local llamafile via a new
  llamafile://<label> model-identifier prefix. Multi-instance
  ChatModelManager (LRU evict, per-label idle reap, CPU
  fallback), claude-hooks-models CLI. See
  docs/llamafile-chat-models.md.
• v1.7 - brings the sqlite_vec provider to full pgvector
  parity: hybrid recall (RRF over vector cosine + BM25 via
  FTS5), idempotent store on whitespace-normalised
  content_hash, and a complete knowledge-graph surface
  (kg_create_entities / kg_add_observations /
  kg_create_relations / kg_search_nodes). The sqlite-vec-mcp
  launcher grows from 3 to 8 tools (full pgvector-mcp parity).
  See docs/sqlite-vec-runbook.md.
• v2 /consultants engine (post-v1.7, on dev) - six-role
  council (planner, researcher w/ optional PLAN-REPORT split,
  critic, synthesizer, opt-in tool_executor, opt-in coder),
  LangGraph-Send x-tier multi-model fan-out with proper
  composition under tool_executor (M11c-3), opt-in BaseStore-backed
  cross-session memory (M8) with per-namespace TTL + Caliber-style
  distillation-on-expiry (M14), and a CitationLinter that verifies
  every path:line claim before the answer leaves the council
  (#204 / #205 / #207). Default-off opt-ins: see
  docs/consultants-roles.md for
  what to enable per question shape.
• Next cut (on dev, tentatively ~v1.13.0 - release trigger
  pending) - two additive, default-OFF feature lines on top of the
  v2 engine, each M12 cohort-2 parity-guarded:
  • /consultants dynamic adversarial review - harden a council
    answer against the wrong-but-plausible failure mode: an engine
    adversary checkpoint (pause before synthesis for an
    assistant-authored red-team brief; auto-resumes on timeout), an
    automated post-synthesis adversary role, a live critic dial
    (lax/normal/strict/adversarial + a free-text attack focus),
    and a skeptic-panel verify_budget - plus a committed
    Workflow-driven council
    (.claude/workflows/consult-with-adversarial-review.mjs)
    that pipelines ask → review → skeptic-panel → accept|follow-up.
    Runbook + worked configure/invoke recipes in
    docs/consultants.md.
  • Per-project /consultants config scope - a
    <project>/.claude-hooks/consultants.toml is now the consistently
    applied active config across every config command and the
    engine, governed by a per-project-only override_user_global
    directive (auto write-scope, with --user/--project/--cwd to
    override on any config set-*, plus a new project-scoped
    config set-override-user-global on|off verb). The real file is
    gitignored (it carries host-specific secrets); a placeholder-only
    .claude-hooks/consultants.example.toml
    template is committed.

Quickstart

git clone https://github.com/mann1x/claude-hooks.git
cd claude-hooks
python3 install.py

The installer auto-detects your MCP servers, creates the config, and wires
hooks into ~/.claude/settings.json. Open a new Claude Code session and
you'll see:

Started with claude-hooks recall enabled (2 provider(s): Qdrant, Memory KG).

Check ~/.claude/claude-hooks.log to confirm hooks are firing.

For the full playbook - LAN-shared proxy setup, systemd unit, statusline
wiring, monitoring, uninstall - see docs/deployment.md.

Releases & versioning

• Current version: v1.12.0 - see CHANGELOG.md for the full history,
  or docs/whats-new.md for the human-readable
  v1.7 highlights (older releases archived alongside:
  v1.4,
  v1.1). Significant unreleased work
  on dev since v1.7.0: /consultants v2 (M8 store, M11c-3
  proper composition, M14 TTL+distillation, CitationLinter) and the
  next-cut feature lines above - dynamic adversarial review
  (checkpoint / role / critic dial / verify budget + Workflow-driven
  council) and per-project config scope (override_user_global). The
  cut (tentatively ~v1.13.0) is triggered manually when ready.
• Tagged releases live on GitHub Releases with auto-generated Source code (zip / tar.gz) archives.
• Branch model: main is the release branch (every commit shippable, tags live here); dev is the working branch (feature work + fixes land here first). See docs/RELEASING.md for the cut procedure.
• To track unreleased work: git log v1.7.0..origin/dev after fetching.
• Optional self-update check (opt-in via install.py or
  update_check.enabled = true): the daemon polls
  https://api.github.com/repos/mann1x/claude-hooks/releases/latest
  at most once every 24 hours and the Stop hook surfaces a one-line
  notice when a newer tag is available. Fails silently on timeouts,
  retries 5× at 5-minute intervals before deferring to the next
  24-hour window, caps notifications at 10 per release, and can be
  disabled at runtime by flipping update_check.enabled in
  config/claude-hooks.json.

What it does

user prompt
   |
   v
[UserPromptSubmit hook] --> HyDE expand --> recall from providers --> decay rank --> inject
   |
   v
Claude responds (knowing the prior context, deterministically)
   |
   v
[Stop hook] --> classify --> dedup check --> store --> extract instincts
   |
   v
[SessionStart on compact] --> full recall re-injection (memory recovery)

Features

Core (v0.1)

• Stdlib only for the core (Qdrant + Memory KG providers, hooks, dispatcher) - no pip install needed. Optional features (pgvector, sqlite-vec, code-graph, MCP server, clustering) pull in their own deps via the [code-graph] / [clustering] / [mcp-server] extras.
• Python 3.10+, runs identically on Linux, macOS, and Windows.
• Auto-detection of MCP servers from ~/.claude.json
• Plugin model: each memory backend is one file (qdrant, memory_kg, pgvector, sqlite_vec)
• OpenWolf integration: injects Do-Not-Repeat and recent bugs from .wolf/ projects
• Non-blocking: every hook exits 0 even on failure

Intelligence (v0.2)

• HyDE query expansion -- generates a hypothetical answer via Ollama before
  searching Qdrant, dramatically improving recall quality. Falls back to raw
  prompt if Ollama is unavailable.
• Attention decay -- memories that haven't been recalled recently fade;
  frequently useful ones strengthen. Tracks history in a JSON file.
• Memory dedup -- before storing, checks for near-duplicates using text
  similarity. Prevents Qdrant from accumulating redundant entries.
• Observation classification -- tags stored memories as fix, preference,
  decision, gotcha, or general for better downstream filtering.
• Compact recall -- when Claude Code compacts context, the SessionStart hook
  re-injects full recalled memory so the model recovers what it lost.
• Instinct extraction -- when a bug-fix pattern is detected (error -> edit),
  auto-extracts it as a reusable markdown instinct file under ~/.claude/instincts/.
• Progressive disclosure -- optional: inject only the first line of each memory
  with a char-count hint, cutting injected context by ~3-5x.
• /reflect synthesis -- CLI command that analyzes recent memories for
  recurring patterns and generates CLAUDE.md rules. Uses Ollama.
• Autonomous consolidation -- CLI command to find duplicates, compress old
  memories, and prune stale ones. Uses Ollama.

Proxy / observability (v0.5+)

• Local HTTP proxy in front of api.anthropic.com (docs/proxy.md)
  that Claude Code hooks can't see on their own. Opt-in via
  config/claude-hooks.json. install.py orchestrates the per-OS
  service - pick "Use the API proxy?" → either [1] install locally
  (systemd unit on Linux, LaunchAgent on macOS, UAC-elevated scheduled
  task on Windows) or [2] point at an existing proxy on the LAN
  (writes ANTHROPIC_BASE_URL into ~/.claude/settings.json for you).

• Warmup short-circuit (proxy.block_warmup: true) - drops the
  subagent-Warmup token drain (anthropics/claude-code#47922)
  without the all-or-nothing side-effects of
  CLAUDE_CODE_DISABLE_BACKGROUND_TASKS. Returns a spec-compliant stub
  (JSON or SSE) so CC never sees an error. The proxy recognises two
  distinct drain patterns and blocks both under the same flag:

  Pattern	Signature (claude_hooks/proxy/metadata.py)	What it is
  CLI "Warmup"	first_user_text == "Warmup"	The keepalive Claude Code sends every few turns to keep the context hot. Cheap per-request but runs thousands of times per day. Classic token drain.
  SDK-CLI subagent priming	cc_entrypoint == "sdk-cli" AND agent_type == "subagent" AND num_messages == 1	The Agent SDK's priming message when a subagent boots. Single user turn, no "Warmup" literal, so it looks like a real prompt to a naïve filter - but it's the same "init the context" intent, just from the SDK-CLI entrypoint. Historically slipped past the old first_user_text check and amplified 300M+ cache reads/day on subagent-heavy workflows.

  Both map to is_warmup=True in request metadata and are blocked
  identically when block_warmup is on. The dashboard's
  warmups_blocked counter aggregates them; scripts/proxy_stats.py --show-sidechain breaks them out.

  Update 2026-04-28 - the literal "Warmup" priming call no
  longer appears in proxy logs starting with Claude Code 2.1.121
  (60 blocks on 04-27 → 0 on 04-28 across 1,300+ requests, on a host
  with no proxy config change). The detector is unchanged; the
  traffic itself is absent. We're keeping block_warmup: true on
  as a safety net in case the pattern returns. See
  docs/issue-warmup-token-drain.md
  for the per-day evidence and the upstream issue thread.

• Live weekly-limit % - proxy captures Anthropic's
  anthropic-ratelimit-unified-* headers into a rolling state file;
  scripts/statusline_usage.py reads it for a compact statusline
  segment, scripts/weekly_token_usage.py --current-usage-pct
  auto-populates from the same file.

• Structured observations (port from thedotmack/claude-mem) -
  hooks.stop.summary_format: "xml" stores memories as
  <observation><type><title><files_modified>… so downstream recall
  can filter by type without prose parsing.

• Metadata-gated rerank - hooks.user_prompt_submit.metadata_filter
  filters candidates by cwd / type / age / tags before vector rerank.

• Caliber grounding proxy (docs/caliber-proxy.md)

  • local OpenAI-compat HTTP server that augments caliber
    with project grounding so caliber init/refresh cite real path:line
    references instead of hallucinated ones. Paired with bin/caliber-smart
    as a drop-in caliber wrapper that falls back to claude-cli when the
    proxy is down.

  ⚠️ The shipped bin/caliber-grounding-proxy defaults
  CALIBER_GROUNDING_UPSTREAM=http://192.168.178.2:11433/v1 - the
  author's home-LAN Ollama proxy. Override via the systemd drop-in
  or shell environment for your install (see the linked doc).

  Caliber-proxy listens on port 38090 by default
  (caliber_proxy.listen_port in config/claude-hooks.json). The
  matching bin/caliber-smart wrapper makes caliber refresh /
  caliber init use the proxy when it's up and fall through to a
  vanilla caliber invocation otherwise. The native-tools agent
  loop is in claude_hooks/caliber_proxy/server.py; design notes for
  picking a small grounding model live in
  docs/gemma4-tool-use-notes.md.

Stats DB + dashboard + behavior canaries

The proxy is more than a forwarder. Every request is parsed for
metadata (effort, model_requested, model_delivered, service_tier,
beta_features, thinking signature bytes, per-tool counts) and rolled
up into a SQLite stats DB. A read-only HTTP dashboard renders the
state, and an opt-in stop-phrase scanner adds behavior-quality canaries
on top:

• Stats DB - schema v5 at ~/.claude/claude-hooks-proxy/stats.db,
  populated by scripts/proxy_rollup.py running every 5 min
  (claude-hooks-rollup.timer). Per-request requests table feeds
  daily / session / model / agent rollups; the same path persists S3
  thinking-depth and S4 per-tool-name canary counts.

• Dashboard - read-only HTTP view on port 38081 (config:
  proxy_dashboard.listen_port). Renders today's request count,
  cache hit-rate, rate-limit utilisation, thinking metrics, tool-use
  canaries, behavior canaries, per-day rollups, agent / model
  breakdowns, beta-feature drift, and the
  stop-phrases × effort × date table that pinned the 2026-05-01
  xhigh quality regression in docs/cc-xhigh-regression-issue.md:

  Run bin/claude-hooks-dashboard for a one-shot start, or install
  the claude-hooks-dashboard.service systemd unit (the proxy
  installer wires it for you). Restart with systemctl restart claude-hooks-dashboard.service after a code change.

• In-stream stop_phrase_guard (proxy.scan_stop_phrases: true)

  • scans every assistant turn against the
    stellaraccident #42796
    canary phrases (config/stop_phrases.yaml, ~8 categories:
    ownership-dodging, permission-seeking, premature-stopping,
    known-limitation labeling, session-length excuses, simplest-fix
    bias, reasoning-reversal, self-admitted error). Hits land in the
    sp_* columns of the stats DB and roll up by day, by effort, and
    by category. Rates per-1k requests show whether a route or a model
    variant has drifted in quality without you noticing the symptoms
    one turn at a time.

• Daily health line - claude-hooks-health.timer fires once a
  day (default 09:07 UTC, after rollups have digested the morning's
  traffic) and runs scripts/proxy_health_oneliner.py. The script
  emits a single line summarising request counts, 5xx / 429 totals,
  and per-effort ownD / permS rates with a ↑ arrow when today
  is ≥ 2× the prior 7-day baseline. Output appended to
  ~/.claude/proxy-health-daily.log and the journal.

For the full schema, query patterns, and dashboard route inventory
see docs/proxy.md. For the upstream-facing PR /
incident drafts that came out of the proxy data, see
docs/issue-warmup-token-drain.md
and docs/cc-xhigh-regression-issue.md.

Code graph (v0.6+)

A built-in, file-based code-structure graph (graphify-out/graph.json

• GRAPH_REPORT.md) auto-built per project. Stdlib-only Python ast
  extractor; opt-in [code-graph] extra adds tree-sitter parsing for
  JS/TS/Go/Rust/Java/Ruby. SessionStart injects a 2-3 KB structural
  summary; per-Grep code_graph_lookup_enabled adds one-line "X is at
  file:line, N callers" hints when the pattern looks like an identifier.

CLI subcommands (python -m claude_hooks.code_graph ...):

Optional extras:

• pip install claude-hooks[code-graph] - tree-sitter-language-pack for multi-language parsing.
• pip install claude-hooks[clustering] - python-louvain + networkx for Leiden-style community detection.
• pip install claude-hooks[mcp-server] - mcp[cli] to spin up an MCP server (python -m claude_hooks.code_graph.mcp_server) exposing the lookup/impact/changes/trace/mermaid/companions tools to any MCP client (Claude Code, Cursor, etc.).

Companion code-graph engines

When you want richer queries than the built-in code_graph provides,
claude-hooks integrates with two heavier engines as opt-in companion
tools (silent no-op when absent):

• axon (RECOMMENDED for Python/JS/TS) - pip install axoniq,
  KuzuDB-backed, dead-code detection, file watcher, 7 MCP tools.
• gitnexus (ALTERNATIVE for 14 languages or multi-repo) - npm i -g gitnexus,
  LadybugDB-backed, hybrid BM25+vector+RRF search, multi-repo group_* tools, 16 MCP tools.

claude-hooks detects either via filesystem checks (binary on PATH +
per-project marker dir + global registry), appends a mcp__axon__* /
mcp__gitnexus__* hint to the SessionStart inject, and spawns the
appropriate analyze on Stop when the turn modified files. Both can
coexist; both reindex paths fire when their respective marker dirs
are present. See COMPANION_TOOLS.md §6-7 for
the install + comparison matrix.

The built-in code_graph always runs as the floor; the companions
upgrade specific dimensions (live MCP queries, dead-code detection,
multi-language coverage) when present.

IDE-style feedback loop (v0.7+)

Closes the "I didn't notice the import error until I ran the code"
gap. Three complementary layers - pick one or stack them:

• PostToolUse ruff hook (built-in, on by default) - runs ruff check on every Python file Claude Code edits with Edit / Write /
  MultiEdit. Diagnostics are injected as
  hookSpecificOutput.additionalContext so the model sees them in the
  very next prompt - before claiming the change is done. ~50 ms cold,
  catches undefined names, unused imports, syntax errors, etc. Config
  under hooks.post_tool_use in config/claude-hooks.json. Pairs
  with a toml_comment_advisor that nudges Claude to leave a
  # why: … line above any non-default value when editing
  hand-edited TOMLs (.claude-hooks/, lsp-engine.toml) - config
  under hooks.post_tool_use.toml_comment_advisor_enabled (default
  on) and toml_comment_advisor_paths (default
  [".claude-hooks/", "lsp-engine.toml"]).
• cclsp (recommended companion, opt-in) - multi-language LSP
  wrapper that fronts pyright / gopls / rust-analyzer / clangd /
  OmniSharp via a single MCP server. Gives Claude Code on-demand
  hover, go-to-definition, find-references, and type diagnostics
  across Python / Go / Rust / C/C++ / C#. See docs/lsp-mcp.md
  for the install + Linux/Windows config. Pairs with the ruff hook:
  ruff is the cheap synchronous Python layer, cclsp is the
  multi-language on-demand layer.

LSP engine (opt-in, v0.7+)

A session-scoped daemon that loads language servers once per
project and follows Claude Code's edits in real time, so
diagnostics queries return in single-digit milliseconds instead of
the 1-3 s pyright cold-start every cclsp call pays. Phases 0-4
shipped (config + lifecycle, daemon + session-affinity locks,
adaptive preload + git watcher, opt-in compile-aware diagnostics,
Windows IPC parity). See docs/lsp-engine.md
for the user guide and docs/PLAN-lsp-engine.md
for the locked design.

The engine is independent of the PostToolUse ruff hook and the
cclsp MCP server; you can run all three or any subset.

Slash command - /setup-compile-aware

Proposes a [compile_aware.commands] block for
.claude-hooks/lsp-engine.toml by detecting build tools in the
current project (Cargo.toml → cargo, tsconfig.json → tsc,
pyproject.toml + mypy → mypy, go.mod → go vet, Makefile, …).
Run this once after enabling the engine to wire the compile-aware
layer; it asks for explicit confirmation before writing.

Scripts

bin/ shim reference

The bin/ directory ships small entry-point shims that auto-detect
the conda env and fall back to system Python. Use these from
settings.json hooks, systemd ExecStart lines, or the shell.

systemd unit reference

systemd/ ships the unit templates the proxy installer drops into
/etc/systemd/system/. Each is User=root by default; adjust the
User= and WorkingDirectory= lines for your install. Linux only;
macOS uses LaunchAgents, Windows uses scheduled tasks (the
installer handles all three).

Requirements

• Python 3.10+. The recall/store core is stdlib-only; only the proxy
  and the optional DB-backed providers (pgvector, sqlite-vec) need wheels.
• Claude Code with hooks support.
• At least one memory backend - pick from the table below. Multiple can
  run simultaneously; the dispatcher fans out recall in parallel.
• (Optional) Ollama for HyDE, /reflect, /consolidate, and as
  the embedder primary for the pgvector / sqlite-vec providers.
  As of v1.4+, Ollama is no longer strictly required for the
  embedder side - the bundled
  llamafile engine (~1.5 GB,
  daemon-supervised) can serve as an Ollama fallback or replace it
  entirely. HyDE / reflect / consolidate still need an Ollama
  (or OpenAI-compatible) chat backend.

Memory backends - pick at install time

Embedding engines (v1.4+) - for the local-embed providers

The pgvector and sqlite-vec providers need an embedder. Qdrant and
Memory KG embed server-side (FastEmbed inside the MCP container /
bundled embedder) and don't need this section - install.py validates
their connectivity and surfaces a one-line note instead.

CompositeEmbedder tries the primary on every embed and drops to the
fallback on EmbedderError. Primary and fallback must agree on
embedding dim (1024 for qwen3-embedding-0.6b) - the installer
warns and the runtime guards.

Conda env + dependency files

The installer creates a claude-hooks conda env (Python 3.11) by default
and pip-installs the requirements files relevant to your enabled
backends. Manual install for reference:

conda create -n claude-hooks python=3.11 -y
conda activate claude-hooks

pip install -r requirements.txt                          # core (httpx[http2])
pip install -r requirements-pgvector.txt                 # if pgvector enabled
pip install -r requirements-sqlite-vec.txt               # if sqlite-vec enabled
pip install -r requirements-dev.txt                      # tests + coverage

The bin/claude-hook shim auto-detects this env (POSIX layout, Windows
Scripts/python.exe, MSYS2 hybrid) and falls back to system python3,
so no activation step is needed at hook runtime.

Install

git clone https://github.com/mann1x/claude-hooks.git
cd claude-hooks
python3 install.py

The installer will:

1. Detect if you have a conda env and offer to create one (optional -- system Python works fine)
2. Scan ~/.claude.json for MCP servers matching Qdrant and Memory KG
3. Verify each server with a real MCP call
4. Write config/claude-hooks.json with your server URLs
5. Merge hook entries into ~/.claude/settings.json (idempotent, tagged _managedBy)
6. Drop PATH wrappers for every bin/* shim so skill CLIs
   (claude-advisor, claude-consultants, …) resolve by bare name
   from Claude Code's bash subprocess. Locations are platform-specific:
   • POSIX (Linux + macOS): ~/.local/bin/<shim> - POSIX sh
     wrapper that execs the absolute repo path. Almost always
     already on PATH; the installer prints a one-line hint if not.
   • Windows: %LOCALAPPDATA%\claude-hooks\bin\<shim> (POSIX
     sh wrapper for the MSYS bash that Claude Code uses) plus a
     <shim>.cmd sibling for native cmd / PowerShell users. The
     installer also prepends that directory to HKCU\Environment\PATH
     via reg add (NOT setx, which silently truncates User PATH
     to 1024 chars), then broadcasts WM_SETTINGCHANGE so new
     processes pick it up without a logoff.
     Wrappers carry an install-time tag string in their first comment
     line so re-runs are idempotent and --uninstall removes only the
     tagged ones - hand-rolled wrappers of the same name are left alone.
7. Ollama chat-side prompts (v1.4+, _setup_ollama_chat).
   First asks whether to use Ollama as a chat backend (validates
   /api/tags), then prompts for HyDE model + fallback +
   num_ctx, and offers a shared-skills shortcut so the
   /reflect and /consolidate skills inherit the same model
   and context. Until v1.4 these settings were hard-coded in
   config.py; the dialog closes that gap. Writes
   hooks.user_prompt_submit.hyde_*, reflect.*, consolidate.*.
8. pgvector + sqlite_vec setup with the embedding-engine
   dialog (v1.4+, _setup_embedding_engine). For each
   local-embed provider you enable, the installer asks:
   • Use Ollama for embeddings? (model + num_ctx; offers
     ollama pull if missing.)
   • OpenAI-compatible primary instead? (mutually exclusive with
     Ollama.)
   • Use llamafile as fallback? (default Yes if a primary is set;
     primary if both Ollama and OpenAI are declined.)
   • llamafile sub-dialog: default model (qwen3-embedding-0.6b,
     16 k ctx) or custom GGUF; GPU mode auto vs cpu -
     auto spawns with -ngl 99 and transparently falls back to
     CPU on VRAM exhaustion; cpu passes --gpu disable.
     On default-model picks the installer downloads the composite
     qwen3-embedding-0.6b-16k.llamafile (~1.5 GB) from the v1.4+
     GitHub Release asset and verifies it against the in-tree
     vendor/llamafile/dist/SHA256SUMS.composite. Second-provider
     invocations default to "same as previous? [Y/n]" so the
     common case is one dialog total. See
     docs/llamafile-integration.md
     for the full architecture.
9. Qdrant + memory_kg validate-only (v1.4+,
   _validate_qdrant_embedding / _validate_memory_kg_embedding).
   Both MCPs embed server-side (FastEmbed inside the Qdrant
   container; bundled embedder in memory_kg); the installer
   probes connectivity, surfaces a one-line note about where the
   model lives, and never overrides their config.
10. Asks "Install /consultants engine?". On yes (opt-in, off
    by default - declines cleanly): creates a dedicated
    claude-hooks-consultants conda env (Py 3.11), pip-installs
    the consultants/ package with its LangGraph + LangServe
    stack, and wires the per-OS service. Two modes:
    • Always-on (default): systemd / launchd / Task Scheduler
      unit keeps the engine resident, ~250 MB steady-state RAM.
      First-turn latency is sub-second.
    • Smart-start (opt-in): the daemon spawns the engine on
      demand and reaps it after idle_timeout_seconds (default
      30 min). Zero RAM idle, ~5-10 s cold start on first request
      after a quiet period.
      Conda is required - install.py aborts with a clear message
      pointing at Miniconda if it's missing, no silent fallback to
      bare venv. Everything goes through the dedicated env so the
      LangGraph dep tree never leaks into the main claude-hooks
      conda env that the test suite runs in.
11. Asks "Use the API proxy?". On yes:

• [1] Local install - pip-installs httpx[http2]>=0.27 into
  the chosen Python env, then drops the per-OS service:
  • Linux - claude-hooks-proxy.service + rollup.service +
    rollup.timer + dashboard.service in /etc/systemd/system/,
    daemon-reload + enable --now.
  • macOS - ~/Library/LaunchAgents/com.claude-hooks.proxy.plist
    (KeepAlive=true, RunAtLoad=true), loaded via launchctl.
  • Windows - UAC-elevated logon-triggered scheduled task
    claude-hooks-proxy (pythonw + run_proxy.py to avoid a
    persistent cmd window).
    Optionally writes ANTHROPIC_BASE_URL=http://127.0.0.1:38080 into
    ~/.claude/settings.json (LAN listen hosts auto-translate to loopback
    on the client side).
• [2] Remote URL - prompts for the proxy URL of an existing host
  on the LAN (e.g. http://192.168.178.2:38080) and writes
  ANTHROPIC_BASE_URL into ~/.claude/settings.json. No local service.
• Idempotent on re-run: already-installed services are detected and
  left alone unless you confirm reinstall.

Installer flags

python3 install.py --dry-run         # show changes, don't write
python3 install.py --non-interactive # CI-friendly, fail on prompts
python3 install.py --uninstall       # remove all claude-hooks entries
python3 install.py --probe           # force tool-probe detection

Verify it works

After install, open a new Claude Code session. You should see the
SessionStart status line. Then check the log:

tail -20 ~/.claude/claude-hooks.log

You should see recall entries for each provider on every prompt.

Configuration

After install, config/claude-hooks.json lives in the repo (gitignored).
Full schema with all options: config/claude-hooks.example.json.

v0.2 features (all opt-in via config)

HyDE model

Default: gemma4:e2b with qwen3:4b fallback. Any small Ollama model
works -- it just needs to produce a short hypothetical answer for search
expansion. If Ollama is down, HyDE degrades gracefully to the raw prompt.

Commands Reference

Slash commands (inside Claude Code)

These are available as skills after running the installer. Type the
command in the Claude Code prompt.

CLI commands (outside Claude Code)

Run these from your terminal in the claude-hooks repo directory.

## Memory analysis
python -m claude_hooks.reflect              # generate CLAUDE.md rules from memory patterns
python -m claude_hooks.reflect --dry-run    # preview without writing

python -m claude_hooks.consolidate          # deduplicate and compress old memories
python -m claude_hooks.consolidate --dry-run

## Installer
python3 install.py                          # interactive install
python3 install.py --dry-run                # show changes, don't write
python3 install.py --non-interactive        # CI-friendly, no prompts
python3 install.py --uninstall              # remove all claude-hooks entries
python3 install.py --probe                  # force MCP tool-probe detection
python3 install.py --episodic-server        # configure as episodic-memory server
python3 install.py --episodic-client URL    # configure as episodic-memory client

## Episodic server (on the server host)
python3 episodic_server/server.py --host 0.0.0.0 --port 11435
systemctl status episodic-server            # if installed as systemd service
journalctl -u episodic-server -f            # follow server logs

## Episodic API (from any host)
curl "http://SERVER:11435/search?q=bcache&limit=5"   # search conversations
curl http://SERVER:11435/health                       # health check
curl http://SERVER:11435/stats                        # index statistics
curl -X POST http://SERVER:11435/sync                 # trigger re-index

## /get-advice CLI (v1.1)
claude-advisor get-model                            # show configured model + ctx_max
claude-advisor set-model qwen3.5:cloud              # set model (auto-probes ctx_max)
claude-advisor set-model qwen3.5:cloud 32768        # set model + pin context length
claude-advisor get-effort                           # show effort tier + budget
claude-advisor set-effort medium                    # low | medium | high | max
claude-advisor get-tools                            # show advisor's project-tool list
claude-advisor set-tools all                        # all known tools
claude-advisor set-tools none                       # tools-off
claude-advisor set-tools read_file,grep             # explicit subset
claude-advisor...