Palace turns a caller's scoped memory question into routed semantic search, then returns useful excerpts with an audit trail that explains exactly where the answer came from.
4memory scopes
50max returned results
200candidate ceiling
0.7/0.3vector/text weighting
01
1Request
LIVE
Ask In Scope
The public memory endpoint accepts a plain question, but it also carries the boundary that decides which memories may answer.
Facade contract
API
POST /api/v1/memory/retrieve
The API receives the query, authenticated tenant, limit, filters, optional room id, and requested memory scope.
KEY
Memory auth validates the caller
The route depends on the memory auth layer, so retrieval uses the tenant attached to the request rather than a caller-supplied tenant id.
MAP
Memory request becomes Palace request
The service converts the facade request into Palace retrieval fields: scope type, scope key, tags, dates, candidate limit, and neighbor options.
validated before search
OK
Known scopes only agent, workspace, session, and tenant_shared are the supported memory boundaries.
!
Key rules are strict agent, workspace, and session need a key; tenant_shared must not include one.
02
2Route
Find The Right Room
Palace routes the query through its room model first, then searches the scoped memory corpus with hybrid vector and text ranking.
Routing gates
1
Resolve explicit room id
If the caller names a room, Palace resolves redirects to the current room lineage target.
DIRECT
2
Score active rooms
Without a room id, Palace scores active rooms using query text, wing, room summaries, tags, and scope terms.
ROUTE
3
Expand weak routes
Low confidence routes can add neighboring tunneled rooms before a global fallback is considered.
EXPAND
4
Run hybrid search
Search combines halfvec cosine similarity and PostgreSQL text rank, then deduplicates to the best chunk per item.
RANK
Scoped hit
Return ranked memory with route trace.
Empty route
Fallback path is recorded in trace.
03
3Return
Answer With Proof
The response includes excerpts, result counts, routed room ids, and trace details so an agent can tell whether recall stayed scoped or broadened.
Broadening rules
Merge01
Explicit tags or low route confidence
Palace can merge global semantic results back into routed room results so tag-filtered memories are not missed.
Fallback02
Room search returns nothing
The service searches the whole selected scope and marks fallback_used plus a completeness warning.
Shared03
Scoped hits are empty or low-signal notes
Tenant-shared memory can be merged, and weak conversation notes are suppressed when better shared knowledge exists.
trace travels with result
Response payload
TXT
SearchResult excerpts
Each hit carries title, summary, source, tags, score, and selected chunk text.
TRC
PalaceRetrieveTrace
Requested scope, route confidence, ranking traces, fallback flags, and status banner are returned for auditability.
CAP
Replay capture
The API captures request parameters, results, trace, and latency for retrieval replay gates.