Slm Recall

slm-recall — Search & Retrieve Memory

Retrieve stored facts, decisions, and past context from SuperLocalMemory using multi-channel retrieval. The golden rule: recall before you remember.

When to use recall vs search vs fetch vs list_recent

Use recall as the default. search is a fallback for zero-result recall on a known exact term. fetch is for when you already know the ID.

Recall-before-remember discipline

Before storing anything new, always call recall first. If a near-duplicate fact already exists, call update_memory(fact_id, content) to refine it rather than creating a duplicate. Duplicates degrade retrieval quality for every future session.

MCP-first workflow

1. Standard recall

recall(
  query="authentication strategy decision",
  limit=20,            # default 20; reduce to 5 for quick pre-task checks
  session_id="<sid>",  # pass the session_id returned by session_init
  fast=None,           # leave unset; see "Fast mode" below for what it controls
)

Real response shape (trimmed to the fields that matter; slm recall --json wraps the same data in a data envelope):

{
  "success": true,
  "results": [
    {
      "fact_id": "f8a2bc91",
      "memory_id": "m7e19ca0",
      "content": "Decided to use JWT with 1h expiry for API auth (2026-06-10)",
      "score": 0.87,
      "confidence": 0.91,
      "trust_score": 0.84,
      "fact_type": "semantic",
      "memory_kind": "decision",
      "memory_kind_state": "confirmed",
      "age_label": "4 months ago",
      "channel_scores": {
        "semantic": 0.88,
        "bm25": 0.61,
        "temporal": 0.72,
        "hopfield": 0.55
      }
    }
  ],
  "count": 1,
  "query_type": "semantic",
  "channel_weights": {
    "semantic": 0.4,
    "bm25": 0.2,
    "temporal": 0.2,
    "hopfield": 0.2
  },
  "channel_status": {
    "semantic": "ok",
    "bm25": "ok",
    "temporal": "empty",
    "hopfield": "ok",
    "spreading_activation": "no_candidates",
    "entity_graph": "no_embedding",
    "profile": "disabled"
  },
  "incomplete_channels": [],
  "retrieval_time_ms": 134,
  "query_id": "q-3f9a",
  "no_confident_match": false,
  "calibration_status": "uncalibrated",
  "calibration_id": null,
  "answer_confidence": null,
  "abstained": false,
  "abstention_reason": null,
  "answer_check_status": "off",
  "answerability": "unjudged",
  "answerability_reason": "disabled"
}

Other fields that can appear: profile (the namespace that answered), project_scope (what a project filter did), tag_scope (what a tags filter did), temporal_frame, reranker_status, and thematic_context. Long contents are clamped and later results can come back as short stubs (truncated / stub on the result); call fetch for the full text.

Read channel_status before concluding that nothing is stored. It reports what each retrieval channel did on this query. channel_weights says how much each channel counts; channel_status says whether it ran at all.

semantic, bm25, temporal, hopfield and spreading_activation each search and return their own candidates. profile is a shortcut that runs before them and can answer directly. entity_graph produces nothing of its own — it re-scores what the others found, by how well each result connects to the entities in your question, which is why it reports no_candidates when the rest come back empty.

empty, no_candidates, disabled and not_configured are normal. error, timeout, no_embedding and warming mean the answer is incomplete, not negative — say so to the user rather than reporting "no memories found". incomplete_channels lists the channels abandoned at the time limit, so two runs of the same question that differ only there are an incomplete answer, not a changed memory.

Refine on low confidence. recall returns confidence signals with every result. If no_confident_match is true (or answer_confidence is low / abstained is true), do NOT invent a memory — rewrite the query into 1–3 more specific sub-queries (split multi-hop questions; try entity names, synonyms, or broader phrasing) and call recall again before concluding nothing was found. A confident match → use it directly. SLM answers from this machine, typically in a second or two, with no server-side LLM round — unless the user turned on the online answer check, which adds one request to that service per recall — and lets you, the calling model, drive this refinement.

abstained means the results shown do not answer the question. If abstained is true, say you don't have it, or ask — never present the returned memories as the answer anyway. abstention_reason distinguishes why: "judged_insufficient" means candidates were found and scored, but none of them actually answers this question; "evidence_floor" / "no_candidates" means nothing was found at all. answer_confidence is a measurement, not a guarantee — treat a low number the same way you'd treat abstained: true. calibration_status: "uncalibrated" means no judge is configured for this recall; in that case abstained only ever reflects the older "nothing found" signal.

abstained: false does not mean the answer was checked. answerability says whether it was: supported (the answer check ran and judged the shown memories sufficient), unsupported (it ran and judged them insufficient) or unjudged (it produced no verdict). answerability_reason gives the cause: judged_fresh or judged_from_memo for a verdict, and for unjudged one of disabled, warming, unavailable, busy, budget_exhausted, no_results, not_a_question or other_profile. An empty result set is unjudged / no_results, which is not evidence that no answer exists (check channel_status). answer_check_note carries a sentence you can show a person.

2. Passing session_id

Pass the session_id returned by session_init, on every recall in that session. It does two things.

1. It carries the conversation forward. Each recall offers its five best-ranked results to a small per-session working set of seven slots. A memory that keeps coming back is reinforced rather than duplicated, and the least-activated slot is the one evicted, so something referenced across several turns is hard to lose. Later recalls in the same session rank the held memories higher, and turn three is not as cold as turn one. The bias is deliberately small — it nudges the order, it never overrides an exact match.
2. It attributes engagement to the session, so a later report_outcome can close the loop on the right recall.

If you omit it, SLM looks for SLM_SESSION_ID, CLAUDE_SESSION_ID or CLAUDE_CODE_SESSION_ID in the environment, then for the host's registered session, and only then falls back to a per-agent label that is never credited to a conversation. Recall still returns correct results either way, but a fallback label means turns start cold and feedback cannot be attributed.

Use the real id, not a made-up one. An id beginning http:, mcp:, cli:, probe:, engine:, agent:, api: or view: is treated as a synthetic per-request label, not a conversation, and is excluded from the working set — inventing one per call would otherwise fill the registry and evict genuine conversations.

3. Fast mode

fast controls one thing: whether the server runs its own internal LLM reformulation round. It does not disable any retrieval channel — every channel and the reranker run either way. Four channels register always: meaning, keyword, entity graph and time. Spreading activation and Hopfield register as a fifth and sixth when their prerequisites are present, so a store sees up to six (profile in channel_status is a shortcut ahead of them, not a search).

Leave it unset. Unset resolves to "skip the internal round", because you are the reasoner: you refine the query yourself using the confidence signals above, and you do it better than a local model would. Pass fast=False only when SLM is deployed with no capable client in front of it.

recall(query="rate limiting approach", limit=5, session_id="<sid>")

4. Keyword fallback via search

When recall returns zero results on a specific term, try search:

search(query="BM25 indexing", limit=20)

Full-text FTS5 with BM25 ranking, no semantic channel. It takes the same kind, tags / tags_match and profile_id arguments as recall (below). The response has success, results (each with fact_id, content, fact_type, confidence, date and the memory-kind fields) and count, but no channel_scores, query_type or answer-check fields.

5. Pull full detail for a known fact

fetch(fact_ids="f8a2bc91,d4c1e203")

Returns the full record for each ID: entities, lifecycle, access_count, importance, observation_date, referenced_date, project. fact_ids may be a comma-separated string or a list. Ids it could not resolve come back in not_found; if none resolve, success is false. Use this when the recall summary (120-char truncation in list_recent) is not enough.

6. Browse recent memories

list_recent(limit=20, kind="", tags="", tags_match="all", profile_id="")

Returns facts newest-first. Content is truncated to 120 chars. Use fetch once you have the fact_id for full content.