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

# recall

> Search memories, get file history, or list entities — unified read tool

Your persistent memory across all AI tools. This is the **unified read tool** — it handles search, file history, and entity overview based on which parameters you provide.

<Info>
  **v0.7.0**: `recall` replaces the previous `recall` + `recall_file` + `list_entities` tools. Mode is auto-detected from params.
</Info>

## Modes

### Search (provide `query`)

Returns memories ranked by a composite score of relevance, heat, momentum, and importance.

```json theme={null}
{
  "query": "Supabase connection pooling",
  "layer": "caveat",
  "max_tokens": 3000
}
```

### File history (provide `path`)

Returns complete edit history of a file across all sessions, with per-edit user-intent context.

```json theme={null}
{
  "path": "server.ts"
}
```

When both `path` and `query` are provided, results from file history and memory search are merged.

### Entity overview (no params)

Returns entity list sorted by momentum — the cheapest "what do I know?" primitive.

```json theme={null}
{}
```

## Parameters

### Search mode

<ParamField body="query" type="string">
  What you want to remember. Free-text, entity name, or FTS5 MATCH expression.
</ParamField>

<ParamField body="entity_name" type="string">
  Narrow results to a specific entity.
</ParamField>

<ParamField body="layer" type="string">
  Filter by memory layer. Accepts aliases (e.g. `warnings` -> `caveat`).
</ParamField>

<ParamField body="altitude" type="string">
  Filter by cognitive altitude: `mission`, `strategy`, `architecture`, `implementation`.
</ParamField>

<ParamField body="mem_type" type="string">
  Filter by memory type: `question`, `comparison`, `decision`, `work`, `outcome`, `learning`, `note`.
</ParamField>

<ParamField body="mem_state" type="string">
  Filter by lifecycle state: `open`, `decided`, `in_progress`, `done`, `stalled`, `parked`, `superseded`.
</ParamField>

<ParamField body="thread_id" type="string">
  Filter by thread ID — returns all memories in a decision chain or session group.
</ParamField>

<ParamField body="band" type="string">
  Filter by heat band: `hot`, `warm`, `cold`, `frozen`.
</ParamField>

<ParamField body="max_tokens" type="number" default="2000">
  Approximate token budget. Iteration stops when this budget is consumed or `limit` is reached, whichever comes first.
</ParamField>

<ParamField body="limit" type="number">
  Hard cap on number of memories returned.
</ParamField>

<ParamField body="offset" type="number" default="0">
  Skip this many top results (pagination). Use `has_more` from prior response to decide next offset.
</ParamField>

<ParamField body="mark_accessed" type="boolean" default="true">
  Set `false` for preview / listing queries that should not bump heat scores.
</ParamField>

### File history mode

<ParamField body="path" type="string">
  File path substring to match against edit history. Can be a filename (`search-services.ts`), partial path (`src/db/`), or full absolute path.
</ParamField>

## Ranking (search mode)

Memories are ranked by a composite score:

```
score = 0.45 * relevance + 0.25 * heat + 0.15 * momentum + 0.15 * importance
```

| Factor     | Weight | Source                             |
| ---------- | ------ | ---------------------------------- |
| Relevance  | 45%    | FTS5 BM25 score + LIKE match       |
| Heat       | 25%    | Ebbinghaus decay since last access |
| Momentum   | 15%    | Entity activity frequency          |
| Importance | 15%    | User-assigned or auto-inferred     |

## Response

### Search mode

Each memory in the response includes:

* `match_reasons` — array explaining why this memory ranked (e.g. `content_match_fts`, `entity_name_match`, `heat:hot`, `pinned`, `caveat_protected`)
* `score_breakdown` — individual scores for transparency
* `has_more` — boolean indicating if more results exist beyond the current page
* `stopped_by` — whether iteration stopped at `tokens`, `limit`, or `end`

### File history mode

| Field                      | Description                                       |
| -------------------------- | ------------------------------------------------- |
| `paths_matched`            | List of file paths that matched the substring     |
| `total_edits`              | Total number of physical edits recorded           |
| `first_edit` / `last_edit` | Date range of edit history                        |
| `sessions_involved`        | Number of distinct sessions that edited this file |
| `daily_breakdown`          | Edits per day, grouped by operation type          |
| `user_intents`             | Distinct user-intent snippets, ordered by recency |
| `linked_memories`          | Related memories with entity name and preview     |

### Entity overview mode

Each entity includes: `name`, `kind`, `memory_count`, layer breakdown (`goal_count`, `caveat_count`, etc.), `momentum_score`.

<Info>
  **Dual search**: Recall uses both FTS5 full-text search (BM25-ranked, trigram tokenizer) and LIKE fallback, merging and deduplicating results. This ensures both exact and fuzzy matches are found, including Japanese text.
</Info>

## Migration from pre-v0.7

| Old call                                       | New equivalent                             |
| ---------------------------------------------- | ------------------------------------------ |
| `recall({ query: "..." })`                     | `recall({ query: "..." })` (unchanged)     |
| `recall_file({ path_substring: "server.ts" })` | `recall({ path: "server.ts" })`            |
| `list_entities({ kind: "project" })`           | `recall({})` (no params = entity overview) |