Skip to content

feat(memory): HeLa-Mem spreading activation retrieval and query-bias tracing#3397

Merged
bug-ops merged 4 commits intomainfrom
3346-hela-mem-spreading-activation
Apr 25, 2026
Merged

feat(memory): HeLa-Mem spreading activation retrieval and query-bias tracing#3397
bug-ops merged 4 commits intomainfrom
3346-hela-mem-spreading-activation

Conversation

@bug-ops
Copy link
Copy Markdown
Owner

@bug-ops bug-ops commented Apr 25, 2026

Summary

  • feat(memory): HeLa-Mem spreading activation retrieval #3346 — Implements HL-F5 spreading activation retrieval for HeLa-Mem: BFS from top-1 ANN anchor with multiplicative path weights, cosine clamping to [0,1], per-step circuit breaker, Hebbian reinforcement on traversed edges, dim-probe at startup, ANN fallback when anchor has no edges. Opt-in via [memory.hebbian] spreading_activation = false (zero-change invariant preserved).
  • feat(memory): add tracing to apply_query_bias and profile_centroid_cached for observability #3379 — Adds tracing::info_span! and structured debug! events to apply_query_bias() and profile_centroid_cached(): all four skip branches (disabled, not_first_person, no_centroid, dim_mismatch), apply branch with centroid dim and weight, and three centroid branches (computed, cache hit with TTL, stale).

New public surface

  • graph::activation::{HelaFact, HelaSpreadParams, hela_spreading_recall}
  • VectorStore::get_points default trait method + Qdrant implementation
  • EmbeddingStore::get_vectors_from_collection
  • GraphStore::qdrant_point_ids_for_entities
  • SemanticMemory::with_hebbian_spread + recall_graph_hela in semantic::recall
  • Config migration step 31b for four new [memory.hebbian] fields

Test plan

  • cargo nextest run --config-file .github/nextest.toml -p zeph-memory -p zeph-config --lib --no-fail-fast — 1546 unit tests pass
  • cargo +nightly fmt --check -p zeph-memory -p zeph-config — clean
  • cargo clippy -p zeph-memory -p zeph-config -- -D warnings — clean
  • Integration tests in crates/zeph-memory/tests/hela_spreading_activation.rs — require Qdrant container, marked #[ignore]
  • Coverage-status rows added for hela-mem-spread and query-bias-tracing (status: Untested)
  • Playbook at .local/testing/playbooks/hela-mem-spreading.md

Closes #3346, #3379

…tracing (#3346, #3379)

Implements HL-F5 spreading activation as an opt-in alternative to pure cosine-ANN
search in HeLa-Mem. Adds observability tracing to the query bias correction path.

Spreading activation (#3346):
- New `hela_spreading_recall()`: BFS from top-1 ANN anchor with multiplicative
  path weights; score = path_weight × cosine.max(0.0)
- Multi-path convergence keeps max path_weight; depth as tie-break
- Fallback to ANN result (real anchor cosine) when anchor has no outgoing edges
- Dim-probe via OnceCell at startup; WARN + empty result on mismatch (#3382 pattern)
- Hebbian reinforcement on traversed top-k edges (excludes synthetic anchor id=0)
- Per-step 8 ms circuit breaker to protect p95 latency NFR (HL-NF3)
- Controlled by new HebbianConfig fields: spreading_activation, spread_depth,
  spread_edge_types, step_budget_ms (all off by default — zero-change invariant)
- New VectorStore::get_points trait method + Qdrant impl for entity vector fetch
- Config migration step 31b; default.toml updated

Tracing (#3379):
- apply_query_bias() and profile_centroid_cached() wrapped in tracing::info_span!
- tracing::debug! for all four bias branches (applied, disabled, not_first_person,
  no_centroid, dim_mismatch) and three centroid branches (computed, cache hit, stale)

Closes #3346, #3379
@github-actions github-actions Bot added enhancement New feature or request documentation Improvements or additions to documentation memory zeph-memory crate (SQLite) rust Rust code changes dependencies Dependency updates config Configuration file changes size/XL Extra large PR (500+ lines) labels Apr 25, 2026
@bug-ops bug-ops enabled auto-merge (squash) April 25, 2026 10:08
bug-ops added 3 commits April 25, 2026 12:09
… in async fns

Replacing span.entered() held across .await in apply_query_bias,
profile_centroid_cached, and hela_spreading_recall hot loop with
#[tracing::instrument] and tracing::debug! to preserve Send bounds.

Fixes zeph-context assembler build failure (E0277).
@bug-ops bug-ops merged commit f0b1937 into main Apr 25, 2026
32 checks passed
@bug-ops bug-ops deleted the 3346-hela-mem-spreading-activation branch April 25, 2026 10:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

config Configuration file changes dependencies Dependency updates documentation Improvements or additions to documentation enhancement New feature or request memory zeph-memory crate (SQLite) rust Rust code changes size/XL Extra large PR (500+ lines)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(memory): add tracing to apply_query_bias and profile_centroid_cached for observability feat(memory): HeLa-Mem spreading activation retrieval

1 participant