Enhanced learning capture: multi-hook pipeline with importance scoring

[AlexMikhalev]

Summary

Upgrade terraphim-agent learn from single-event capture (PostToolUse failures only) to a multi-hook pipeline with importance scoring and quality gating before storage.

Motivation

Inspired by vibeship-spark-intelligence 12-stage pipeline. Current terraphim learning capture has three gaps:

1. Only captures PostToolUse failures -- misses PreToolUse context (what was the agent trying to do?) and UserPromptSubmit (developer's original intent)
2. No importance scoring -- all failures stored equally. A typo correction failure and a critical data loss near-miss get the same treatment.
3. No quality gating -- raw events stored directly. No filtering for noise, staleness, or redundancy.

Proposed Pipeline

Event Capture (3 hooks)
 |
Importance Scoring (categorize + score 0-100)
 |
Quality Gate (filter noise, deduplicate, check freshness)
 |
Storage (existing terraphim_persistence)
 |
Retrieval (enriched queries via terraphim-agent learn query)

Implementation Plan

1. Extend hook capture (terraphim_hooks)

Add capture handlers for:

• PreToolUse: Record intended action + context before execution
• UserPromptSubmit: Record developer's original instruction
• Retain existing PostToolUse failure capture

Link events: PreToolUse + PostToolUse for the same tool invocation should be correlated (shared invocation ID).

2. Importance scoring

Score each captured event on:

• Severity: Was this a near-miss for data loss, security issue, or just a typo?
• Novelty: Has this pattern been captured before? (Use Aho-Corasick automata against existing learnings)
• Actionability: Can this learning be turned into a concrete rule or hook?

Score 0-100. Configurable threshold for storage (default: 30).

3. Quality gate

Before persisting, filter:

• Deduplication: Aho-Corasick match against existing learnings corpus (use automata, not LLM)
• Freshness: If a semantically similar learning was captured in the last 7 days, skip
• Noise: Filter common false positives (network timeouts, transient CI failures)

4. Enriched retrieval

Extend terraphim-agent learn query to:

• Filter by importance score range
• Filter by event type (PreToolUse, PostToolUse, UserPromptSubmit)
• Show correlated event chains (intent -> action -> outcome)

Affected Crates

• terraphim_hooks (extend capture to 3 hook types)
• terraphim_agent (extend learn subcommand with enriched queries)
• terraphim_automata (used for deduplication matching)
• terraphim_types (add ImportanceScore, EventCorrelation types)

Estimated Effort

~1 day for pipeline skeleton + importance scoring. Ongoing refinement of scoring heuristics.

Related

• Extend session store with real-time event capture and health invariants #597 Event sourcing (learning events should flow into the event store)
• Epic: Ouroboros-inspired agent infrastructure patterns #595 Epic: Ouroboros-inspired patterns (constitutional guardrails could define what severity=critical means)

[AlexMikhalev]

Implementation Complete (2026-04-10)

Commit 2d1aef1 includes Phase E features alongside Phase G.

Changes:

• ImportanceScore struct: error_severity, repetition_count, recency, has_correction, total
• Weighted scoring: 0.3 severity + 0.3 repetition + 0.2 recency + 0.2 correction
• importance: Option on CapturedLearning (backward compat)
• LearnHookType enum: PreToolUse, PostToolUse, UserPromptSubmit
• process_hook_input_with_type() routes per hook type
• PreToolUse: queries past learnings, warns on similar commands
• UserPromptSubmit: parses correction patterns ('use X instead of Y')
• All handlers fail-open
• list_all_entries() sorts by importance descending
• learn_hook_type CLI parameter (defaults to post-tool-use)
• 18 new tests covering scoring, routing, correction parsing

Verification (right-side-of-v): PASS -- all 10 verification items confirmed

[AlexMikhalev]

Implemented and verified. Closing as part of sprint housekeeping.