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

# recall_memory: Zero-RTT Local Semantic Search

> recall_memory runs vector similarity search entirely on-device against LanceDB, returning ranked, decrypted results with sub-25ms p99 latency.

<style>
  {`
      main, article, .prose {
        margin-left: 2.5cm !important;
        margin-right: 2.5cm !important;
      }
      `}
</style>

`recall_memory` is an **MCP tool** that performs vector similarity search locally against the on-device LanceDB index. Because both the index and the embedding model run inside the agent's host process, semantic reads never require a network round-trip.

<Note>
  `recall_memory` is exposed as an MCP tool by `@sovseal/mcp-server`. `@sovseal/sdk` (`v1.0.0+`) and `sovseal-sdk` (`v1.1.0+`) also expose `recall(query, opts)` via framed IPC to the local native host (`~/.sovseal/native-host/run.sh`). If the native host is absent, version-mismatched (`protocolVersion: 1`), or times out, SDK calls throw/raise `EngineUnavailableError` (`reason`: `"not-installed"` | `"version-mismatch"` | `"timeout"`) with zero cloud fallback. See [Quickstart](/platform/quickstart).
</Note>

***

## Arguments

```ts theme={null}
recall_memory({ query: string, topK?: number })
```

That is the complete input schema. There is **no** `minScore`, no `filters`, and no metadata query language — filtering by tags, categories, or lineage is not implemented.

## Return value

Top-K results in descending composite-score order:

```json theme={null}
[
  { "id": "a86938e9-…", "text": "I prefer Vitest over Jest for new TypeScript projects.", "score": 1.4353 }
]
```

Note that `score` is a **composite** value and is not bounded to `[0,1]` — see the ranking formula below.

***

## Latency

| Operation                    | p50     | p95     | p99     |
| ---------------------------- | ------- | ------- | ------- |
| `recall_memory` (warm)       | 6.1 ms  | 10.4 ms | 21.8 ms |
| First call (cold model load) | \~1.2 s | —       | —       |

All at **0 RTT**. Reproduce: `pnpm --filter @sovseal/mcp-server test bench-v2`.

## Query embedding cache

The MCP server keeps an **LRU cache of query embeddings**, default capacity **256**, tunable with `SOVSEAL_EMBEDDING_CACHE_SIZE` (set `0` to disable). Only *queries* are cached — every stored memory is unique by construction, so caching writes would never hit.

<Note>
  The embedding model is `Xenova/all-MiniLM-L6-v2` (ONNX, quantized, \~22 MB), auto-downloaded to `~/.sovseal/models/` on first run and SHA-256 pinned before load.

  The browser extension currently runs a **different** model (`intfloat/multilingual-e5-small`) — both are 384-dim, but the two surfaces do not share one vector space today. A memory captured in the browser is not guaranteed to rank correctly when recalled from the MCP server, or vice versa.
</Note>

***

## Reinforcement-aware ranking

Raw vector distance is only the first pass. `recall_memory` over-fetches **8 × topK** candidates by vector distance, then re-ranks by a composite score before returning the top `topK`:

```text theme={null}
score = similarity × decay × reinforcement
```

| Factor            | Definition                                                                                                                                                                                                               |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **similarity**    | `max(0, 1 − distance / 2)` — cosine-equivalent of the L2 distance to the query vector.                                                                                                                                   |
| **decay**         | `exp(−λ_type · days_since(last_reinforced))`. Half-lives by type: **episodic 14d**, **semantic 90d**, **procedural 180d**. Override with `SOVSEAL_DECAY_EPISODIC`, `SOVSEAL_DECAY_SEMANTIC`, `SOVSEAL_DECAY_PROCEDURAL`. |
| **reinforcement** | `1 + ln(1 + reinforce_count)` — memories restated more often rank higher.                                                                                                                                                |

The practical consequence: **a frequently-reinforced older fact can out-rank a fresher, higher-raw-similarity one-off.** That is what makes recall behave like memory rather than a plain nearest-neighbour index.

<Note>
  **Why local recall doesn't re-verify cryptographically.** Recall against the local LanceDB index does not run Verified Semantic Recall. The local index sits inside your trust boundary — an attacker who can write arbitrary bytes to `~/.sovseal/db/` has already compromised the device, and VSR would not help. VSR defends the **network**: a malicious replication server, a MITM, or a compromised endpoint. See [Verified Semantic Recall](/platform/core-concepts/verified-semantic-recall).
</Note>

***

## Calling it

```json theme={null}
// Tool call
{
  "name": "recall_memory",
  "arguments": {
    "query": "what testing framework do I prefer",
    "topK": 3
  }
}

// Result
[
  {
    "id": "a86938e9-de49-4a87-89de-edb62bef27b8",
    "text": "I prefer Vitest over Jest for new TypeScript projects.",
    "score": 1.4353
  }
]
```

Recall works with the network fully unavailable. This was verified with DNS blackholed browser-wide: store in 144 ms cold, semantic recall in 38 ms, **zero outbound requests**, with the top hit ranking correctly on a query sharing no content words with the stored memory.

***

## Next steps

<CardGroup cols={2}>
  <Card title="Memory Model" icon="layer-group" href="/platform/core-concepts/memory-model">
    How `type`, `reinforce_count`, and `provenance` are set at write time.
  </Card>

  <Card title="Verified Semantic Recall" icon="shield" href="/platform/core-concepts/verified-semantic-recall">
    The cryptographic check that runs when records are restored from the replication server.
  </Card>
</CardGroup>