feat(phase5): explainable memory operations (v3.10)#160
Open
salishforge wants to merge 1 commit into
Open
Conversation
Feature 2 of the Phase 5 split (umbrella #129): every retrieval can say why, and any warm memory can be asked where it stands. - query(): opt-in explain=true attaches ExplanationFactor[] per result (rank_score, epistemic_status weight, search_mode, temporal_decay) - explainMemory() + GET /memory/:id/explain?warm_id= reports scores, access patterns, and standing against the sleep-cycle score thresholds. Flags are scoped honestly (would_evict_by_threshold, would_flag_low_confidence): capacity eviction and the outcome / contradiction revision channels depend on live cross-table state and are deliberately not predicted here. - memforge_explain MCP tool wired to the real client method; TS + Python SDKs including both resilient wrappers; OpenAPI entries - query cache key extracted to queryKey() in cache.ts so the explain flag's participation in the key is unit-testable without Redis - warm_id validated to int8 range at REST and MCP boundaries; invalid agent ids on /explain return 400 like sibling routes No schema migration — pure code feature. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011xCqQo49d3CEbn6oEvb3Ru
This was referenced Jul 26, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Feature 2 of the Phase 5 split from umbrella #129 (F1 landed in #137, F5+F6 in #136/#138). No schema migration — pure code feature.
explain=trueonGET /memory/:id/query— each result carries anExplanationFactor[](rank_score,epistemic_statusweight 1.0/0.5/0.2,search_mode,temporal_decaywhen decay is active).GET /memory/:id/explain?warm_id=+MemoryManager.explainMemory()— state report for a single warm memory: scores, epistemic status, access patterns, and standing against the sleep-cycle score thresholds. The outlook flags are deliberately scoped (would_evict_by_threshold,would_flag_low_confidence); capacity eviction and outcome/contradiction-driven revision depend on live cross-table state and are not predicted.memforge_explainMCP tool wired to a real client method (the umbrella version was a stub returningmemoryHealth), TS + Python SDK methods including both resilient wrappers, tool-definitions, OpenAPI entries.warm_idbounded to int8 at REST + MCP boundaries (was: Postgres 22003 → 500), invalid agent id on/explainreturns 400 like sibling routes, query cache key extracted toqueryKey()incache.tsso the explain flag's key participation is pinned by unit tests without Redis.Test evidence
npm run type-checknpm run linttests/explainable-memory.test.ts(new)npm run test:httpnpm run test:integrationnpm run test:epistemic-confidencePre-existing issues surfaced by review (out of scope, filing separately)
QueryResultdataclass rejects unknown response keys — already incompatible with v3.8/v3.9 response fields at HEAD./entitiesand/graphreturn 500 (not 400) for invalid agent ids — same pattern this PR fixes for/explain.epistemicquery param missing from the OpenAPI query-path spec (F1 gap).🤖 Generated with Claude Code
https://claude.ai/code/session_011xCqQo49d3CEbn6oEvb3Ru