phase-memory/docs/activation-quality.md

Activation Quality

phase-memory activation can now be planned from deterministic graph neighborhoods and event paths without requiring embeddings, vector stores, or LLM ranking.

Graph Neighborhood Retrieval

retrieve_graph_neighborhood expands from seed nodes across graph edges.

Supported controls:

• maximum hops
• edge kind filters
• in, out, or both direction
• phase filters
• memory kind filters

Candidates receive deterministic scores based on explicit priority, graph distance, phase, lifecycle state, confidence, source-backed status, freshness, and policy allowance.

Event Path Activation

select_event_path activates ordered event ids from a structured MemoryPath. Active paths are selected by default. Abandoned, merged, or compacted paths can be included explicitly when a caller wants to inspect inactive branches.

Token Estimation

TokenEstimator is a protocol. The default implementation is WordCountTokenEstimator, which keeps tests deterministic and dependency-free. Provider-specific tokenizers can be supplied later without changing retrieval contracts.

Quality Report

activation_quality_report emits local metrics suitable for later export to evaluation systems:

• selected expected nodes
• omitted required nodes
• policy-denied required nodes
• token budget utilization
• stale item activation count
• provenance coverage
• source span coverage
• explanation coverage

The fixture tests/fixtures/activation-quality-report.json pins a small expected report for regression tests.