> ## Documentation Index
> Fetch the complete documentation index at: https://docs.klio.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# recall

> Retrieve relevant memories for the current org before acting.

The read verb. An agent should call this before answering questions about a
project — it is the half of the handover that makes the other half worth doing.

## Parameters

<ParamField path="query" type="string" required>
  What to search the team's memory for. Search matches on meaning and on exact
  wording at the same time, so you can phrase it the way you would ask a
  colleague, or paste the identifier you are actually looking for.
</ParamField>

<ParamField path="scope" type="'org' | 'agent' | 'private'" default="org">
  `org` searches the shared team memory plus your own private memories and the
  projects you belong to. `private` narrows to your own memories only. `agent`
  searches what this agent identity wrote and is not a privacy boundary. See
  [Scope](/concepts/scope).
</ParamField>

<ParamField path="space" type="string">
  Optional space slug, to confine the search to one project's store.
</ParamField>

<ParamField path="project" type="string">
  Optional project identifier, to narrow results without switching space.
  Matches a git remote URL, a repository root path, a project id, or a
  display name. See [Scope](/concepts/scope#narrowing-a-recall).
</ParamField>

<ParamField path="limit" type="integer" default="10">
  Maximum memories to return. Between `1` and `50`.
</ParamField>

## Examples

<CodeGroup>
  ```json Basic theme={null}
  {
    "query": "how do we handle auth errors in the API?"
  }
  ```

  ```json Scoped to a space theme={null}
  {
    "query": "when do invoices generate?",
    "space": "billing",
    "limit": 5
  }
  ```

  ```json This agent's private notes theme={null}
  {
    "query": "what was I in the middle of?",
    "scope": "agent"
  }
  ```

  ```json An exact identifier theme={null}
  {
    "query": "KLIO_METRICS_TOKEN"
  }
  ```
</CodeGroup>

## Notes on behaviour

<AccordionGroup>
  <Accordion title="Superseded memories do not come back" icon="rotate-left">
    If a decision has been contradicted by a newer one, recall returns the
    current version only. You are not asked to reconcile the two — that is the
    point of the retire step in the [handover loop](/concepts/handover-loop).
  </Accordion>

  <Accordion title="Reads see writes immediately" icon="bolt">
    A memory written by another agent a second ago is available to the next
    recall. There is no push to already-running agents, so an agent mid-session
    sees new state only when it calls `recall` again.
  </Accordion>

  <Accordion title="Exact wording counts, so paste the identifier" icon="magnifying-glass">
    Recall runs two searches and combines them. One matches meaning, so a
    paraphrase finds a memory that used different words. The other matches the
    text itself, so a rare literal finds the memory that contains it.

    This matters because the two fail in opposite places. A search for a flag
    name, an error string, a commit hash or a function name is the case where
    meaning-based search is weakest: the token is rare, so it carries little
    signal, and memories that are merely *about* the same topic can crowd out
    the one memory that actually names it. Pasting the literal is not a worse
    query than describing it. It is usually the better one.

    An identifier is matched as its parts, in order. `pool_pre_ping` matches
    text containing `pool pre ping` adjacent and in that sequence, so a memory
    that happens to use all three words separately does not match.
  </Accordion>

  <Accordion title="Tune limit down, not up" icon="sliders">
    The default of `10` suits most questions. Raising it toward `50` spends the
    model's context on progressively less relevant results — usually a sign the
    query should be narrower, or the memories should live in a
    [space](/concepts/scope).
  </Accordion>

  <Accordion title="project fills, it does not exclude down to just that project" icon="folder-tree">
    Passing `project` returns that project's memories first, then fills any
    remaining slots (up to `limit`) with unfiled memories — never with another
    project's. If a query has few hits inside the project, expect the rest of
    the page to be org-wide unfiled results, not padding from elsewhere.
  </Accordion>
</AccordionGroup>

<Tip>
  Results carry a memory id. Pass it to [`forget`](/tools/forget) to retract
  something that surfaced and should not have.
</Tip>