feat(memory): surface recall scores and add a graded relevance floor

[prakashUXtech]

What

soul recall scores memories two separate ways, and the two never meet. Each store's search() keeps a candidate if it shares any token with the query, so one shared word is enough to win a slot. BM25 gets computed too, but only inside compute_activation as the spread term, so it never reaches a result. And recall --json has no score field at all.

This PR puts the activation score on every recalled entry and turns the binary gate into a graded cutoff you can configure.

Why

Issue #247 audited the session-start soul recall mandate. Recall already drops zero-overlap matches, so a vague query comes back empty instead of padded. The part #247 flagged is the floor itself. Today it is a binary gate: any token overlap, however slight, takes a slot. Setting a graded threshold means the score has to reach the result first, and right now it is stuck inside the scorer.

Changes

• activation.py: activation_breakdown() returns the activation total along with its component terms. compute_activation() now calls through to it, so existing callers see no change.
• recall.py: RecallEngine.recall() scores each candidate once, writes the activation score to recall_score, and drops candidates below relevance_floor. The floor checks raw token overlap rather than the activation total, so a recency or emotion boost cannot carry an off-topic memory past it.
• search.py: DEFAULT_RELEVANCE_FLOOR and passes_relevance_floor() replace the bare score > 0.0 literal in each store's search().
• types.py: adds MemoryEntry.recall_score — a runtime-only field that stays out of the .soul file.
• cli/main.py: recall --json emits a score per result, and a --min-relevance flag exposes the floor.

The default floor stays 0.0, so existing recalls behave the same as before. A higher cutoff is opt-in through relevance_floor or --min-relevance. Raising the default would quietly drop matches that current callers expect to see.

Testing

Smoke test (tests/test_cli/test_recall_score.py): soul recall --json emits a score field per result, a recall returns scored results, and --min-relevance drops a weak match.

End-to-end (tests/test_retrieval.py::TestRecallScoresAndFloor): populate a store, query it, then check that every result carries a score, results come back ordered by score, and a weak match below the floor is dropped while the strong match stays.

Results:

• uv run pytest tests/test_retrieval.py -q — 25 passed
• uv run pytest tests/ -q --ignore=tests/e2e — 3067 passed, 1 skipped (the skip is a known pre-existing failure, unrelated to this change)

Docs updated in this PR: memory-architecture.md (recall behavior, new "Recall scores and the graded relevance floor" section), cli-reference.md (--min-relevance flag and the score JSON field), api-reference.md (relevance_floor parameter), and the GAP-ANALYSIS.md recall row.

Closes #247

[github-actions]

Issues (must fix)

• No evidence of local testing found. Please include terminal output or screenshots.

Heads up

• Large PR detected (801 lines across 16 files). Consider splitting into smaller PRs.

Please update your PR to address these points.

[github-actions]

Security scan: review needed

Potentially dangerous code patterns detected in changed files. A maintainer should verify these are intentional and safe.### src/soul_protocol/runtime/memory/manager.py

2282:            search_strategy: Optional SearchStrategy for pluggable retrieval (v0.2.2).

src/soul_protocol/runtime/memory/recall.py

33:#   Access timestamps are updated on retrieval (strengthens future recall).

src/soul_protocol/runtime/soul.py

833:            search_strategy: Optional SearchStrategy for pluggable retrieval (v0.2.2).
1050:            search_strategy: Optional SearchStrategy for pluggable retrieval (v0.2.2).
1321:    def last_retrieval(self) -> RetrievalTrace | None: