Skip to content

17 Quality Hooks Integration

Heinrich Krupp edited this page Nov 6, 2026 · 2 revisions

Quality and Hooks Integration

Reviewed 2026-11-06 against v12.6.0 and current GitHub main. Python 3.11+ is required.

Claude Code hooks can use stored quality metadata while selecting context. That selection is distinct from server-side quality evaluation and query reranking. The plugin and legacy hooks installer are alternative installation paths, not two layers to enable together.

Choose the installation path

The repository's plugin guide describes the currently experimental plugin path. The Python installer remains the legacy alternative. Check their prerequisites and existing configuration before installation.

For the legacy path, from a repository checkout:

cd claude-hooks
python install_hooks.py --help

After reviewing the installer options, a basic installation is:

python install_hooks.py --basic

Use that installation's test instructions. Do not copy an old test-hooks.js path or assume the optional features are installed with the base Python package. Installing hooks changes client configuration; keep an existing configuration and merge endpoint/credential settings rather than replacing it with a fragment.

Configure the service connection

In the legacy hooks configuration, the HTTP endpoint is under memoryService.http, and the self-signed-certificate opt-in belongs under memoryService. Merge this fragment into the existing ~/.claude/hooks/config.json:

{
  "memoryService": {
    "protocol": "http",
    "http": {
      "endpoint": "http://127.0.0.1:8000",
      "apiKey": "replace-with-your-api-key"
    },
    "allowSelfSignedCerts": false
  }
}

Replace the URL and key with the running service's settings. For a remote server, use trusted HTTPS. The client verifies certificates by default; do not disable verification for the whole Node process. Plugin configuration may differ: follow the plugin guide rather than assuming it reads the legacy JSON file.

What the hooks score

The legacy scorer considers time, tags, content relevance, local content heuristics, backend quality and type information. Conversation-aware selection adds another context signal. Weights vary by mode and configuration; the old fixed five-factor table was not a universal formula.

Backend quality is taken from numeric memory.metadata.quality_score, then a numeric top-level memory.quality_score, otherwise a neutral 0.5. A legitimate zero must remain zero. The source checks numeric values instead of using value || 0.5.

The backend score can reflect a human override, model evaluation or implicit signals. The hooks consuming that score do not establish which provider produced it, and loading context is not proof that the memory was rescored.

REST search and response shape

The current client uses POST /api/search for ordinary and quality-weighted semantic search. There is no separate /api/search/semantic route to choose when boosting is off. REST search returns results, whose entries contain memory and similarity_score; the legacy client unwraps these entries into memory objects.

An authenticated REST quality-weighted request:

MEMORY_BASE_URL=http://127.0.0.1:8000
MEMORY_API_KEY=replace-with-your-api-key
curl --fail -X POST "$MEMORY_BASE_URL/api/search" \
  -H "X-API-Key: $MEMORY_API_KEY" -H "Content-Type: application/json" \
  -d '{"query": "authentication architecture", "n_results": 5, "quality_boost": true, "quality_weight": 0.3}'

The existing legacy memory client exposes queryMemoriesHTTP(query, limit, options), with options.qualityBoost and options.qualityWeight. Do not replace its implementation with a historical standalone snippet.

MCP uses a different schema. Arguments to memory_search:

{"query": "authentication architecture", "limit": 5, "quality_boost": 0.3}

Evaluation and human feedback

The authenticated REST evaluation endpoint can update one memory's machine-origin score. Use the procedure in Quality System; do not trigger an evaluation for every result merely to render a session header. Check hook configuration and logs to determine whether that installation actually requests evaluation.

Machine computed_quality, human user_rating and effective quality_score are separate fields. Human feedback takes precedence for the effective score without erasing the machine origin. Search boosting and blending implicit signals into stored scores also have separate settings; explicitly set the blend configuration if you do not want it inherited from search-boost settings.

Verify the integration

  1. Confirm the HTTP service is reachable with the same URL and credentials as the hooks process.
  2. Restart Claude Code after installation or configuration changes and check its active hooks/plugin setup.
  3. Test from the intended project with known relevant memories. Zero loaded memories can be legitimate when the store is empty or filters exclude them.
  4. Inspect a known memory's quality metadata and the hook logs. Separate connection, retrieval, scoring and injection failures.
  5. Compare a fixed query with and without quality weighting before increasing its influence.

No fixed retrieval-precision gain is promised. Keep private content and credentials out of diagnostic reports. See Troubleshooting, the legacy memory client and scorer. Historical integration phases remain in the page history.

Clone this wiki locally