Skip to content

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

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.

POST /api/memory/recall, from request to response. Optional stages depend on configuration.signet daemonopt graphopt rerankeropt sessionKeyClientCLI · SDK · MCPDaemonrequest processRecall ownerholds memories.dbModelsembed · rerankPOST /api/memory/recall1auth · recall permission2resolve agent + read policy3recall job · 30 s4embed query5query vector6FTS5 · hints · vector7paths · traversal8authorize every candidate before reading contentrerank (redacted)9scores10rank · hydrate · redact11record in dedupe ledger12results + meta13apply minScore14200 results, meta15
POST /api/memory/recall, from request to response. Optional stages depend on configuration.
  1. Client to Daemon: POST /api/memory/recall
  2. Daemon: auth · recall permission
  3. Daemon: resolve agent + read policy
  4. Daemon to Recall owner: recall job · 30 s
  5. Recall owner to Models: embed query
  6. Models to Recall owner: query vector
  7. Recall owner: FTS5 · hints · vector
  8. opt graph:
  9. Recall owner: paths · traversal
  10. Note: authorize every candidate before reading content
  11. opt reranker:
  12. Recall owner to Models: rerank (redacted)
  13. Models to Recall owner: scores
  14. Recall owner: rank · hydrate · redact
  15. opt sessionKey:
  16. Recall owner: record in dedupe ledger
  17. Recall owner to Daemon: results + meta
  18. Daemon: apply minScore
  19. 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.

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 or aggregate is on and auth mode is not local
Clients
signet recall · SignetClient.recall() · MCP memory_search, signet_recall
Terminal window
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".

200 OK
{
"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 }
}
}
  • query string · required

    Search text. Trimmed; empty is rejected. Exact dates in the text start temporal recall.

  • limit number · default 10

    Results to return. The daemon clamps it to 1..50.

  • type string

    Memory type, such as preference.

  • tags string

    Comma-separated tags. A memory must contain every tag, by substring match.

  • who string

    Author, such as claude-code.

  • pinned boolean

    Only pinned memories.

  • importance_min number

    Lowest importance to include.

  • since, until ISO 8601

    Bounds on created_at.

  • project string

    Project filter. A project-scoped token overrides it.

  • scope string

    Exact memory scope, such as world:alpha. Omitting it excludes scoped memories.

  • time object

    Explicit temporal window: start, end, facets, mode. See Dates in a query.

  • minScore number

    Drop results below this score. Applied after ranking.

  • keywordQuery string

    Text for the keyword lane only, when it should differ from query.

  • agentId string · default parsed from sessionKey, then $SIGNET_AGENT_ID

    Agent whose read policy applies.

  • sessionKey string · or header x-signet-session-key

    Enables session dedupe.

  • includeRecalled boolean · default false

    Return rows already recalled in this session.

  • sourceOnly boolean · default false

    Search source chunks and native artifacts only.

  • aggregate boolean · default false

    Return one synthesized answer. See Aggregate recall.

  • aggregateBudget small, medium, large · default small

    Recall queries an aggregate may run: 3, 5, or 8.

  • saveAggregate boolean · default true

    Save the aggregate answer as a memory. Needs remember permission.

  • recallSurface string

    Telemetry label: explicit_api, tool_call, prompt_injection, dashboard, or other.

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.

  • results array

    Ranked results. Fields below.

  • query string

    The query as received.

  • method hybrid or keyword

    hybrid when vector search contributed. Timeline responses are always keyword.

  • meta object

    Counts, coverage, and timings. Fields below.

  • aggregate object

    Present for aggregate recall.

  • entities array

    Entity context, when graph traversal produced it.

Each result has:

  • id

    Memory id. Results that are not stored memories use a prefix: source-chunk:, native-artifact:, summary:, constructed:, transcript:, or temporal:.

  • content

    Text with detected credentials replaced by [redacted credential]. Stored memories are unchanged.

  • content_length, truncated

    Original length and whether content was shortened.

  • score

    Final score, two decimal places.

  • source

    Lane that produced the result. See result sources.

  • type, tags, pinned, importance, who, project, created_at

    Stored memory fields. tags is a comma-separated string.

  • source_id, session_id, source_path, visibility, scope

    Present when known.

  • supplementary

    true for supporting context, such as a summary card.

  • already_recalled

    true when returned again because of includeRecalled.

meta has:

  • totalReturned

    Number of results.

  • hasSupplementary

    true when any result is supplementary.

  • noHits

    true when recall finished and found nothing.

  • vectorCompleteness

    complete, recent-window, or unavailable.

  • partial, degradation

    Set when coverage was incomplete. See Partial results.

  • reranker

    { kind, model?, fallback? }; kind is llm, cross-encoder, embedding, or none.

  • timings

    totalMs and per-stage durationMs.

  • dedupe

    Session dedupe counts. See Session dedupe.

  • temporal

    The resolved window, facets, and content query.

  • transcriptEvidence

    { returned, ranking?, failed? } for the transcript lane.

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.

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.

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.suppressed counts skipped rows.
  • includeRecalled: true returns them again, marked already_recalled: true.
  • meta.dedupe.failedOpen: true means the ledger was unavailable and nothing was skipped.
  • Rows that minScore removes still count as recalled.

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.

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: true runs normal recall, may plan follow-up queries, and returns one synthesized answer built from unique evidence.

  • aggregate.stoppedReason is complete, no_evidence, router_unavailable, or synthesis_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.usage reports tokens, cost, and duration per stage when the provider reports them, and null otherwise.

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.

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

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.

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
Terminal window
curl -s 'http://localhost:3850/api/memory/search?q=editor+preferences&limit=5'
  • q required

    Search text.

  • limit default 10

    Clamped to 1..50.

  • type, tags, who

    Same as the POST body.

  • pinned

    1 or true.

  • importance_min, since, until

    Same as the POST body.

  • project

    A project-scoped token overrides it.

  • agentId, agent_id

    Also read from x-signet-agent-id. A scoped credential that names another agent gets 403.

  • sessionKey, session_key

    Also read from x-signet-session-key.

  • includeRecalled, include_recalled

    1 or true.

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.

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
  • q

    FTS5 query. Without it, filters alone select rows.

  • limit default 20 with q, 50 without

    Clamped to 1..50.

  • type, tags, who, importance_min, since

    Filters.

  • pinned

    1 or true.

  • distinct

    who returns the list of authors instead. Other parameters except the agent are ignored.

  • agentId, agent_id

    Agent whose read scope applies, or all. Also read from x-signet-agent-id.

200 OK
{
"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, score is the raw FTS5 BM25 value. Lower is better.
  • If q is not valid FTS5 syntax, the route falls back to a substring match ordered by newest, with no score.
  • With filters only, score is 1.0 for 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.

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
SignetClient generated getMemorySimilar
Terminal window
curl -s 'http://localhost:3850/memory/similar?id=6f1c2a9e-0d4b-4e7a-9a51-3c8f2b7d1e40&k=5'
  • id required

    The anchor memory.

  • k default 10

    Results to return, clamped to 1..50.

  • agentId, agent_id

    Agent whose read scope applies. Also read from x-signet-agent-id.

  • type

    Only this memory type.

200 OK
{
"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.