Explicit Recall Surface Alignment

Signet is consolidating its fragmented TypeScript recall surfaces into a single canonical explicit recall engine and API, aiming to reduce duplication and preserve metadata. The plan keeps hybridRecall() and /api/memory/recall as primary building blocks while thinning or removing legacy helpers like handleRecall() and ad hoc formatters. This restructuring will make recall easier to evolve by ensuring improvements land in the correct layer.

Explicit Recall Surface Alignment Problem Signet’s TypeScript recall behavior is split across too many surfaces that share some plumbing but diverge in orchestration and presentation: /api/memory/recall exposes the richest retrieval path through hybridRecall . handleUserPromptSubmit uses recall differently because prompt-submit is a hot-path injection surface with confidence gates, dedup, and fallback channels. /api/hooks/recall is a harness-oriented recall surface that currently wraps the same engine but still acts like a separate product boundary.- CLI, MCP, and connector consumers flatten results differently and often throw away metadata such as source labels, scores, type, and provenance. platform/daemon/src/hooks.ts still contains an older handleRecall helper that appears to be legacy logic instead of a live source of truth. The result is not six different retrieval engines, but it is still a fragmented recall product: - one strong engine, - one prompt-submit orchestration path, - several renderers and wrappers, - at least one likely-dead helper, - too many places where useful metadata gets discarded. This makes recall harder to evolve because every improvement risks landing in the wrong layer. Goals - Establish one canonical TypeScript explicit recall engine. - Establish one canonical explicit recall response contract. - Keep prompt-submit recall intentionally small, fast, and distinct from explicit recall. - Reduce or remove duplicate helper logic that does not own real product behavior. - Make explicit recall consumers preserve useful metadata instead of turning rich results into anonymous bullet lists. Non-goals - No Rust parity work in this spec. - No retrieval-model redesign, re-ranking redesign, or graph search redesign. - No attempt to make prompt-submit into a rich query product. - No new memory types, schema changes, or pipeline extraction changes. - No deep-memory-search or LLM-escalation work. Current surface inventory Keep as primary building blocks | Surface | File | Role | |---|---|---| hybridRecall | platform/daemon/src/memory-search.ts | Canonical explicit recall engine | | prompt-submit orchestration | platform/daemon/src/hooks.ts | Hot-path injection control flow, not a rich query surface | | temporal fallback helpers | platform/daemon/src/temporal-fallback.ts | Supporting continuity fallback | | transcript fallback helpers | platform/daemon/src/session-transcripts.ts | Supporting continuity fallback | /api/memory/recall | platform/daemon/src/daemon.ts | Canonical explicit recall API | Keep, but thin down | Surface | File | Current issue | |---|---|---| /api/hooks/recall | platform/daemon/src/daemon.ts | Useful harness entry point, but should remain a thin wrapper | CLI signet recall | surfaces/cli/src/commands/memory.ts | Loses too much structure in display | MCP memory search | platform/daemon/src/mcp/tools.ts | Returns raw text payload without a stronger recall contract | OpenClaw /recall rendering | integrations/openclaw/connector/src/index.ts | Flattens results into plain content bullets | Likely remove or collapse | Surface | File | Current issue | |---|---|---| handleRecall | platform/daemon/src/hooks.ts | Looks like legacy standalone recall logic rather than a live source of truth | | ad hoc formatter duplication | multiple consumers | Rich metadata is repeatedly discarded in slightly different ways | Proposed architecture 1 Canonical explicit recall engine platform/daemon/src/memory-search.ts remains the only retrieval engine for explicit TypeScript recall. hybridRecall already owns: - keyword + vector merge, - filtering, - scoping, - reranking hooks, - graph/traversal support, - supplementary context, - expansion behavior. This spec does not replace that engine. It treats it as the source of truth. 2 Canonical explicit recall API /api/memory/recall becomes the canonical API surface for explicit recall. Other explicit recall surfaces should: - wrap it, - render it, - or constrain it for a specific caller, but should not grow separate retrieval behavior unless that difference is required by an explicit contract. 3 Prompt-submit remains separate Prompt-submit recall stays in handleUserPromptSubmit and remains a distinct product boundary: - lightweight injection only, - confidence-gated, - fallback-friendly, - deduplicated, - budget-limited. Prompt-submit is not the place for the richer “query product” behavior. It is allowed to use recall, but it should not become recall’s main presentation layer. 4 Fallbacks remain supporting channels Temporal and transcript fallbacks remain valuable, but only as fallback channels when structured memory is weak or missing. They should not grow into peer retrieval engines that compete with hybridRecall . Contract decisions A Retrieval source of truth Source of truth: hybridRecall Not a source of truth: CLI formatting, MCP formatting, connector formatting, prompt-submit injection formatting B Explicit recall source of truth Source of truth: /api/memory/recall Thin wrapper candidate: /api/hooks/recall Alias only: /api/memory/search C Prompt-submit source of truth Source of truth: handleUserPromptSubmit - It may call hybridRecall , but it is not responsible for becoming the canonical explicit recall experience. Consolidation plan Phase 1, dead-weight audit - Confirm whether handleRecall in platform/daemon/src/hooks.ts is actually used anywhere meaningful. - Remove it if dead, or demote it to a thin wrapper if it still serves a compatibility role. - Document any remaining call sites that still bypass the canonical recall path. Phase 2, explicit recall response contract Define a canonical response contract for explicit recall that all TypeScript consumers can rely on. This does not require changing the retrieval engine, only tightening the product contract around it. The contract should preserve at least: - result ordering, - score, - source, - type, - date/provenance, - supplementary-result distinction, - no-hit behavior. The contract may later grow richer shaped sections for explicit recall, but that presentation belongs outside prompt-submit. Phase 3, consumer alignment Refit the following consumers to preserve useful metadata and stop flattening everything into anonymous snippets: - CLI signet recall - MCP memory search - OpenClaw /recall - any harness-oriented recall formatting that currently strips source and provenance Phase 4, wrapper discipline Keep /api/hooks/recall only if it has a real harness-oriented purpose: - different auth/session behavior, - stricter wrapper semantics, - harness compatibility surface. If it does not need its own contract, it should stay visibly thin. Validation handleRecall is either removed or proven necessary with documented call sites. /api/memory/recall remains the authoritative explicit recall endpoint. /api/hooks/recall does not diverge into its own retrieval engine.- CLI, MCP, and connector recall displays expose source labels and preserve useful metadata from the canonical response. - Prompt-submit injection remains lightweight and separate from explicit recall shaping. Success metrics - One obvious TypeScript engine owns explicit recall behavior. - One obvious TypeScript API owns explicit recall response semantics. - Prompt-submit stays fast and small. - Consumer surfaces stop collapsing recall into metadata-free bullets. - Future recall changes can be made in one place and seen predictably across wrappers. Open decisions - Whether /api/hooks/recall should remain a public compatibility surface long-term or collapse entirely into /api/memory/recall . - Whether the canonical explicit recall response contract should stay raw JSON-first or also define a higher-level shaped presentation contract for CLI/MCP consumers. - Whether explicit recall should expose a first-class “summary / sources / gaps / no-hit” product contract at the API layer or only in selected renderers.