Contextual memory injection hook (UserPromptSubmit + PreToolUse)

[emp3thy]

Summary

Surfaces the relevant curated memories (semantic + reflections, project + general) at the moment they matter, by whole-word keyword-matching against the current prompt / tool-input — closing the "loaded once at SessionStart, then ignored" gap. No new deps, no embeddings, no schema migration.

What's added

• services/keywords.py — keyword extraction + whole-word matching (pure, no deps).
• services/relevant.py — retrieve_relevant(backend, …) fetches the small, already-ranked sets through the StorageBackend abstraction (works sqlite + agentcore), keyword-filters, ranks by (#hits, managed order), caps; format_relevant() renders the additionalContext block.
• hooks/contextual_inject.py — UserPromptSubmit + PreToolUse hook; never raises, always exits 0.
• config.py — BETTER_MEMORY_CONTEXT_INJECT_MODE (userprompt|pretool|both(default)|off).
• cli/install_hooks.py — registers both events (matcher Skill|Task|Write).
• Docs: docs/hooks-setup.md, README.md, website/configuration.md.

Design notes

• Scope is curated memories only (semantic + reflections); observations/knowledge excluded.
• No dedup (proximity/recency intentional) — documented deferred option.
• Verified against CC hooks docs: UserPromptSubmit/PreToolUse additionalContext is injected as a system reminder Claude reads. Whether PreToolUse fires for the built-in Skill/Task tools is environment-dependent (probe deferred) — UserPromptSubmit is the reliable backbone.

Testing

pytest (100 affected tests green), ruff (zero net-new; pre-existing debt untouched), pyright (0 on new modules). End-to-end smoke: piping a "write the plan" prompt surfaces the planning-guardrails reflection (conf 0.90).

Spec: docs/superpowers/specs/2026-06-14-contextual-memory-injection-hook-design.md
Plan: docs/superpowers/plans/2026-06-14-contextual-memory-injection-hook.md

🤖 Generated with Claude Code

[github-actions]

🟢 Claude BugBot Analysis

No bugs found in the changes. The contextual_inject hook, retrieve_relevant service, keyword extraction helpers, config resolver, and installation registration are all correctly implemented. Backend method signatures (retrieve, semantic_list) match the call sites, the build_backend import is valid, the oversized-stdin sentinel pattern is correct, the with closing(conn) block properly scopes the database connection, and the two-pass remove-then-add approach in merge_settings_json preserves idempotency for the new UserPromptSubmit and PreToolUse entries.

No bugs were detected in this PR.