Recall and search
Recall finds the memories that matter for a query and returns them ranked, with a record of how each one was found.
Four endpoints read memories. Use POST /api/memory/recall unless one of the others fits better.
| Endpoint | Use it for | Engine |
|---|---|---|
POST /api/memory/recall |
Agent and application recall with every filter | Hybrid recall |
GET /api/memory/search |
The same recall from a query string | Hybrid recall |
GET /memory/search |
Dashboard keyword search and the author list | Direct FTS5 |
GET /memory/similar |
Memories close to one you already have | Vector only |
How recall runs
Section titled “How recall runs”The daemon validates the request, then hands the search to the recall owner, a separate process that holds the database. The owner embeds the query, gathers candidates from every enabled lane, authorizes them, ranks them, and returns the result.
- Client to Daemon: POST /api/memory/recall
- Daemon: auth · recall permission
- Daemon: resolve agent + read policy
- Daemon to Recall owner: recall job · 30 s
- Recall owner to Models: embed query
- Models to Recall owner: query vector
- Recall owner: FTS5 · hints · vector
- opt graph:
- Recall owner: paths · traversal
- Note: authorize every candidate before reading content
- opt reranker:
- Recall owner to Models: rerank (redacted)
- Models to Recall owner: scores
- Recall owner: rank · hydrate · redact
- opt sessionKey:
- Recall owner: record in dedupe ledger
- Recall owner to Daemon: results + meta
- Daemon: apply minScore
- Daemon to Client: 200 results, meta
The request process never opens the database. If the recall owner is unavailable or misses its deadline, the request fails; nothing runs the search elsewhere.
POST /api/memory/recall
Section titled “POST /api/memory/recall”Runs hybrid recall for one query and returns ranked memories.
- Permission
recall- Body
- JSON, up to 10 MiB
- Deadline
- 30 s in the recall owner
- Rate limit
auth.rateLimits.recallLlm, 60 per minute per token, when the LLM reranker oraggregateis on and auth mode is notlocal- Clients
signet recall·SignetClient.recall()· MCPmemory_search,signet_recall
Example
Section titled “Example”curl -s http://localhost:3850/api/memory/recall \ -H 'Content-Type: application/json' \ -d '{"query": "editor preferences", "limit": 5, "sessionKey": "sess-1"}'Outside local auth mode, add -H "Authorization: Bearer $SIGNET_TOKEN".
signet recall "editor preferences" --limit 5 --session-key sess-1 --jsonimport { SignetClient } from "@signet/sdk";
const signet = new SignetClient();const { results } = await signet.recall("editor preferences", { limit: 5, sessionKey: "sess-1",});{ "results": [ { "id": "6f1c2a9e-0d4b-4e7a-9a51-3c8f2b7d1e40", "content": "User prefers vim keybindings in every editor", "content_length": 44, "truncated": false, "score": 0.92, "source": "hybrid", "type": "preference", "tags": "editor,ui", "pinned": false, "importance": 0.9, "who": "claude-code", "project": null, "created_at": "2026-02-21T10:00:00.000Z" } ], "query": "editor preferences", "method": "hybrid", "meta": { "totalReturned": 1, "hasSupplementary": false, "noHits": false, "vectorCompleteness": "complete", "timings": { "totalMs": 14.25, "stages": [ { "name": "memory_fts", "durationMs": 1.12 }, { "name": "query_embedding_wait", "durationMs": 8.4 }, { "name": "final_rank", "durationMs": 0.08 } ] }, "dedupe": { "enabled": true, "contextEpoch": 0, "suppressed": 0, "repeatedReturned": 0 } }}Request
Section titled “Request”-
querystring · requiredSearch text. Trimmed; empty is rejected. Exact dates in the text start temporal recall.
-
limitnumber · default 10Results to return. The daemon clamps it to
1..50. -
typestringMemory type, such as
preference. -
tagsstringComma-separated tags. A memory must contain every tag, by substring match.
-
whostringAuthor, such as
claude-code. -
pinnedbooleanOnly pinned memories.
-
importance_minnumberLowest importance to include.
-
since,untilISO 8601Bounds on
created_at. -
projectstringProject filter. A project-scoped token overrides it.
-
scopestringExact memory scope, such as
world:alpha. Omitting it excludes scoped memories. -
timeobjectExplicit temporal window:
start,end,facets,mode. See Dates in a query. -
minScorenumberDrop results below this score. Applied after ranking.
-
keywordQuerystringText for the keyword lane only, when it should differ from
query. -
agentIdstring · default parsed from sessionKey, then $SIGNET_AGENT_IDAgent whose read policy applies.
-
sessionKeystring · or header x-signet-session-keyEnables session dedupe.
-
includeRecalledboolean · default falseReturn rows already recalled in this session.
-
sourceOnlyboolean · default falseSearch source chunks and native artifacts only.
-
aggregateboolean · default falseReturn one synthesized answer. See Aggregate recall.
-
aggregateBudgetsmall, medium, large · default smallRecall queries an aggregate may run: 3, 5, or 8.
-
saveAggregateboolean · default trueSave the aggregate answer as a memory. Needs
rememberpermission. -
recallSurfacestringTelemetry label:
explicit_api,tool_call,prompt_injection,dashboard, orother.
The daemon reads camelCase fields. It also accepts aggregate_budget and save_aggregate. The SDK and the other canonical clients translate snake_case options before sending; see client compatibility.
Response
Section titled “Response”-
resultsarrayRanked results. Fields below.
-
querystringThe query as received.
-
methodhybrid or keywordhybridwhen vector search contributed. Timeline responses are alwayskeyword. -
metaobjectCounts, coverage, and timings. Fields below.
-
aggregateobjectPresent for aggregate recall.
-
entitiesarrayEntity context, when graph traversal produced it.
Each result has:
-
idMemory id. Results that are not stored memories use a prefix:
source-chunk:,native-artifact:,summary:,constructed:,transcript:, ortemporal:. -
contentText with detected credentials replaced by
[redacted credential]. Stored memories are unchanged. -
content_length,truncatedOriginal length and whether
contentwas shortened. -
scoreFinal score, two decimal places.
-
sourceLane that produced the result. See result sources.
-
type,tags,pinned,importance,who,project,created_atStored memory fields.
tagsis a comma-separated string. -
source_id,session_id,source_path,visibility,scopePresent when known.
-
supplementarytruefor supporting context, such as a summary card. -
already_recalledtruewhen returned again because ofincludeRecalled.
meta has:
-
totalReturnedNumber of results.
-
hasSupplementarytruewhen any result is supplementary. -
noHitstruewhen recall finished and found nothing. -
vectorCompletenesscomplete,recent-window, orunavailable. -
partial,degradationSet when coverage was incomplete. See Partial results.
-
reranker{ kind, model?, fallback? };kindisllm,cross-encoder,embedding, ornone. -
timingstotalMsand per-stagedurationMs. -
dedupeSession dedupe counts. See Session dedupe.
-
temporalThe resolved window, facets, and content query.
-
transcriptEvidence{ returned, ranking?, failed? }for the transcript lane.
Errors
Section titled “Errors”Every error body has an error string. Recall failures also return results: [].
| Status | error |
When |
|---|---|---|
| 400 | Invalid JSON body |
The body is not JSON. |
| 400 | query is required |
query is missing or blank. |
| 400 | Invalid aggregateBudget... |
aggregateBudget is not small, medium, or large. |
| 400 | time.start is required... and similar |
time is malformed. The message names the field. |
| 401 | authentication required |
No bearer token outside local mode. |
| 403 | ...lacks 'recall' permission |
The token’s role cannot recall. |
| 403 | ...lacks 'remember' permission |
An aggregate save without remember. Send saveAggregate: false. |
| 413 | payload too large |
The body is over 10 MiB. |
| 429 | rate limit exceeded |
The recallLlm bucket is empty. Wait for Retry-After. |
| 503 | Recall unavailable while database integrity is unresolved |
The database is blocked pending repair. See repairGuidance. |
| 503 | Recall failed |
A required provider is down, such as the LLM reranker. |
| 500 | Recall failed |
Any other failure, including a missed 30 s deadline. |
Behavior
Section titled “Behavior”scope matches one exact scope string. When you omit it, recall returns only memories with no scope. Scope does not select agent or session isolation; use agentId and sessionKey for that.
Session dedupe
Section titled “Session dedupe”With a sessionKey, recall skips memories it already returned in the current context epoch for that session and agent. The same ledger covers direct recall, hook recall, and prompt injection.
meta.dedupe.suppressedcounts skipped rows.includeRecalled: truereturns them again, markedalready_recalled: true.meta.dedupe.failedOpen: truemeans the ledger was unavailable and nothing was skipped.- Rows that
minScoreremoves still count as recalled.
Dates in a query
Section titled “Dates in a query”An exact date in query, such as 2026-05-13, 2026/05/13, or May 13 2026, starts temporal recall. Ranges such as 2026-05-13/2026-05-15 and 2026-05-13/15 also work.
- A date alone returns a timeline of what happened in that window.
- A date plus words filters by the date and searches the words. Empty slots fill with other memories from the window, marked
source: "temporal_window".
Pass time to set the window directly. end defaults to 24 hours after start. facets accepts session, source, captured, observed, occurred, and valid. mode is auto, timeline, or filter.
Partial results
Section titled “Partial results”Recall can return 200 with incomplete coverage. Treat the results as useful but not exhaustive.
meta.degradation |
Cause |
|---|---|
fts_incomplete |
The keyword index is rebuilding. A bounded scan filled in. |
graph_traversal_timeout |
Traversal hit the owner deadline. meta.graphPartial is true. |
graph_traversal_failed |
Traversal failed. meta.graphError explains it. |
Aggregate recall
Section titled “Aggregate recall”aggregate: true runs normal recall, may plan follow-up queries, and returns one synthesized answer built from unique evidence.
aggregate.stoppedReasoniscomplete,no_evidence,router_unavailable, orsynthesis_failed.- With evidence but no synthesis, the evidence returns with
aggregate.partial: true. - Saved answers are memories with
source_type: "aggregate-recall". Repeating the same request returns the same saved memory. aggregate.usagereports tokens, cost, and duration per stage when the provider reports them, andnullotherwise.
Summary card
Section titled “Summary card”With memory.pipelineV2.reranker.useExtractionModel on and limit of at least 2, recall may prepend a synthesized summary: source: "llm_summary", supplementary: true, id summary:<sha1-12>. It is not stored.
Result sources
Section titled “Result sources”| Group | source values |
|---|---|
| Search lanes | hybrid, vector, keyword, hint |
| Graph | structured, sec, traversal, ka_traversal, graph, constructed |
| Temporal | temporal, temporal_candidate, temporal_hybrid, temporal_topic, temporal_window, temporal_<facet> |
| Sources | source, source_obsidian, source_import, native_memory, transcript |
| Synthesized | llm_summary |
Client compatibility
Section titled “Client compatibility”Clients default limit to 10, and the daemon clamps every request to 50.
| Client | Scope | Score threshold | Differences |
|---|---|---|---|
| Core, SDK | Any scope string | minScore |
None |
| OpenClaw | Not exposed | min_score |
Exposes a subset of fields |
| OpenCode | Exact scope string | min_score |
None |
| Hermes Agent | Through agent_scoped |
score_min |
Exposes a subset of fields |
| Unreal | World or player namespace | Not exposed | NPC default 6, max 20; always sets includeRecalled |
Request vectors shared by every runtime live in platform/core/contracts/recall-request-v1.json.
GET /api/memory/search
Section titled “GET /api/memory/search”Runs the same hybrid recall as POST /api/memory/recall, with parameters in the query string.
- Permission
recall- Deadline
- 30 s in the recall owner
- Response
- Same as
POST /api/memory/recall
curl -s 'http://localhost:3850/api/memory/search?q=editor+preferences&limit=5'-
qrequiredSearch text.
-
limitdefault 10Clamped to
1..50. -
type,tags,whoSame as the POST body.
-
pinned1ortrue. -
importance_min,since,untilSame as the POST body.
-
projectA project-scoped token overrides it.
-
agentId,agent_idAlso read from
x-signet-agent-id. A scoped credential that names another agent gets 403. -
sessionKey,session_keyAlso read from
x-signet-session-key. -
includeRecalled,include_recalled1ortrue.
This route has no scope, so it returns only unscoped memories. It does not accept time, aggregate, minScore, or keywordQuery, and it has no recallLlm rate limit.
Errors match the POST route, except that 400 is only query is required.
GET /memory/search
Section titled “GET /memory/search”Legacy keyword search used by the dashboard. It queries FTS5 directly and does not use the recall pipeline. New clients should use POST /api/memory/recall.
Results follow the requesting agent’s read policy, the same scope recall uses. The agent comes from agentId or agent_id, the x-signet-agent-id header, an agent:<id>: session key, or the credential’s scoped agent. Without any of these it is the daemon’s configured agent ($SIGNET_AGENT_ID, otherwise default). agentId=all searches every agent’s memories and requires admin permission, which local mode grants; the dashboard uses it. Deleted and superseded memories are excluded, and distinct=who lists only the authors that agent can read.
- Permission
recall
-
qFTS5 query. Without it, filters alone select rows.
-
limitdefault 20 with q, 50 withoutClamped to
1..50. -
type,tags,who,importance_min,sinceFilters.
-
pinned1ortrue. -
distinctwhoreturns the list of authors instead. Other parameters except the agent are ignored. -
agentId,agent_idAgent whose read scope applies, or
all. Also read fromx-signet-agent-id.
{ "results": [ { "id": "6f1c2a9e-0d4b-4e7a-9a51-3c8f2b7d1e40", "content": "User prefers vim keybindings in every editor", "created_at": "2026-02-21T10:00:00.000Z", "who": "claude-code", "importance": 0.9, "tags": "editor,ui", "type": "preference", "pinned": 0, "score": -4.2 } ]}- With
q,scoreis the raw FTS5 BM25 value. Lower is better. - If
qis not valid FTS5 syntax, the route falls back to a substring match ordered by newest, with noscore. - With filters only,
scoreis1.0for pinned rows and decayed importance otherwise. - With
distinct=who, the response is{ "values": ["alice", "bob"] }.
| Status | error |
When |
|---|---|---|
| 401, 403 | Same as recall. Also 403 for agentId=all without admin permission. |
|
| 500 | Search failed |
The query failed. |
GET /memory/similar
Section titled “GET /memory/similar”Returns memories whose embeddings are closest to an existing memory. The anchor and the results follow the requesting agent’s read policy, resolved as for GET /memory/search (without all). Neighbors are taken from the nearest 4 × (k + 1) candidates, at most 200, and then filtered to that scope, so fewer than k can come back. When that happens and the candidate cap was reached, the response includes "truncated": true: closer memories outside the scope filled the candidate window, and in-scope neighbors further out were not searched.
- Permission
recall- Clients
SignetClientgeneratedgetMemorySimilar
curl -s 'http://localhost:3850/memory/similar?id=6f1c2a9e-0d4b-4e7a-9a51-3c8f2b7d1e40&k=5'-
idrequiredThe anchor memory.
-
kdefault 10Results to return, clamped to
1..50. -
agentId,agent_idAgent whose read scope applies. Also read from
x-signet-agent-id. -
typeOnly this memory type.
{ "results": [ { "id": "9b0e4d1a-7c2f-4f3e-8d6a-1e5b2c9f7a03", "content": "User uses vim mode in VS Code", "type": "preference", "tags": ["editor"], "score": 0.87, "confidence": null, "created_at": "2026-02-22T09:30:00.000Z" } ], "completeness": "complete"}The anchor is never in its own results. completeness and searchedWindow report how much of the vector index was scanned, as in meta.vectorCompleteness.
| Status | error |
When |
|---|---|---|
| 400 | id is required |
id is missing. |
| 403 | A scoped credential names another agent. | |
| 404 | No embedding found for this memory |
The anchor has no embedding, is deleted or superseded, or is outside the agent’s read scope. |
| 500 | Similarity search failed |
The search failed. |

