---
title: "MCP Tools"
image: "https://recall.edheltzel.codes/og.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://recall.edheltzel.codes/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Tools

All 9 tools available to any MCP client connected to the Recall MCP server (`recall-memory`).

---

## memory_search

FTS5 keyword search across all memory tables. Use before asking the user to repeat anything.

Use `table` when you need a **hard filter** to one record type. Use `bias_type` when you want one type to appear first but still want useful matches from other tables.

**Parameters**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| query | string | yes | — | Search query. FTS5 supports `AND`, `OR`, `NOT`, `prefix*`, `"exact phrase"` |
| project | string | no | — | Filter results to a specific project name |
| table | string | no | — | Hard-filter search to one table: `messages`, `loa`, `decisions`, `learnings`, `breadcrumbs` |
| bias_type | string | no | — | Softly boost one table type in ranking without filtering other matches. Same allowed values as `table`; prefer `table` when you need only one type. |
| limit | number | no | 10 | Maximum number of results to return |

**Returns:** Matching records as text: table, id, project, created time, a content preview, and Record Provenance (`verbatim`, `user_authored`, `extracted`, `derived`, or `unknown` for legacy rows that predate provenance). A global query with zero keyword hits and no `table` filter retries hybrid search.

```js
// Only decisions
memory_search({ query: "kubernetes auth", project: "my-app", table: "decisions", limit: 10 })

// Prefer decisions, but keep matching learnings/messages/LoA/breadcrumbs
memory_search({ query: "kubernetes auth", project: "my-app", bias_type: "decisions", limit: 10 })
```

**When to bias:** use `bias_type: "decisions"` for “what did we decide,” `"learnings"` for “what did we learn,” `"breadcrumbs"` for “where did we leave off,” `"loa"` for LoA extracts (Automatic-capture or Curated), and `"messages"` for raw conversation traces.

---

## memory_hybrid_search

Combined keyword + semantic search, unless `~/.agents/Recall/config.json` has a `query` key. A named or command win returns that text. A local win stays on the configured mode (semantic, keyword, or hybrid). See [architecture](https://recall.edheltzel.codes/docs/architecture/#harness-steps).

**Parameters**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| query | string | yes | — | Natural language search query |
| project | string | no | — | Filter results to a specific project name |
| limit | number | no | 10 | Maximum number of results to return |

**Returns:** Formatted text. The default hybrid path includes fused relevance scores and Record Provenance; configured query harnesses return their selected mode's output.

```js
memory_hybrid_search({ query: "how did we handle rate limiting", project: "my-app" })
```

---

## memory_recall

Get recent context — LoA entries, decisions, and breadcrumbs. Good for orienting at the start of a session.

**Parameters**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| limit | number | no | 5 | Number of recent entries to return per category |
| project | string | no | — | Filter results to a specific project name |

**Returns:** Recent records grouped by category: Library of Alexandria entries, decisions, and breadcrumbs — each annotated with its Record Provenance.

```js
memory_recall({ limit: 5, project: "my-app" })
```

---

## context_for_agent

Call this before spawning any agent via the Task tool. Uses the configured query harness when that key is present, otherwise hybrid search.

**Parameters**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| agent_task | string | yes | — | The task or prompt you plan to give the agent |
| project | string | no | — | Current project name for filtering |

**Returns:** Formatted context block for the agent prompt. The configured local modes (`keyword`, `semantic`) return search hits for the task only. The hybrid path also adds recent LoA titles and active decisions, and says whether local memory looks sufficient or Brave search is recommended.

```js
context_for_agent({ agent_task: "Refactor the auth middleware", project: "my-app" })
```

---

## memory_add

Add structured records during a session. Use this to capture decisions, learnings, and work-in-progress breadcrumbs as they happen.

For `memory_add` and `recall add`, learning tags pass through the same scrubber as record text before insertion into SQLite: recognized secrets become `[REDACTED:<kind>]`, and invisible or bidirectional Unicode controls are stripped. The tool response or CLI output reports the kinds redacted. The scrubber recognizes specific credential patterns; it cannot guarantee removal of every secret.

Never submit API keys, tokens, passwords, or credential-bearing snippets to memory writes or session dumps. Redact them before recording (for example, `[REDACTED:api-key]`), because stored records can resurface in future sessions' L0/L1 context. Before dumping a session that touched credentials, say so and confirm with the user.

**Parameters**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| type | string | yes | — | Record type: `"decision"`, `"learning"`, or `"breadcrumb"` |
| content | string | yes | — | Main content |
| detail | string | no | — | Additional detail — reasoning for decisions, solution steps for learnings |
| project | string | no | — | Project name |
| tags | string | no | — | Comma-separated tags (applies to learnings) |
| confidence | string | no | — | Confidence level: `"high"`, `"medium"`, or `"low"` — applies to decisions and learnings |
| importance | number | no | 5 | Importance on a 1-10 scale. Surfaces higher-importance records earlier in L1 at session start. LoA has a floor of 5. (Added in v0.7.0.) |

**Returns:** Confirmation with the new record's id and table.

Records created through `memory_add` are automatically stamped with Record Provenance `user_authored`. There is intentionally no provenance parameter — provenance is write-path metadata, not a caller claim (see `adr/0001-record-provenance-automatic-write-path-metadata.md`).

```js
memory_add({ type: "decision", content: "Use PostgreSQL over MySQL", detail: "Better JSON support and JSONB indexing" })
memory_add({ type: "learning", content: "bun:sqlite uses $param syntax", detail: "Not :param like better-sqlite3", tags: "bun,sqlite" })
memory_add({ type: "breadcrumb", content: "Auth refactor in progress — do not touch middleware until complete" })
memory_add({ type: "decision", content: "Ship onboarding first", importance: 9 })
```

---

## memory_stats

Get database statistics including record counts per table and total database size. No parameters.

**Returns:** Sessions, messages, LoA entries, decisions, learnings, breadcrumbs, and total database size on disk.

```js
memory_stats()
```

---

## loa_show

Show a full Library of Alexandria entry. The body is the `fabric_extract` column (name, not the writer). For entry types, see [LoA terminology](https://github.com/edheltzel/Recall/blob/main/CONTEXT.md#loa).

**Parameters**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| id | number | yes | — | LoA entry ID (use `memory_search` or `memory_recall` to find IDs) |

**Returns:** Full LoA record including title, extract body, and metadata. Do not assume every entry is Fabric `extract_wisdom`.

```js
loa_show({ id: 1 })
```

---

## memory_dump

Persist an explicitly supplied conversation session into SQLite. Claude, OpenCode, and Pi have native transcript discovery; other hosts must supply visible messages instead of relying on an assumed private transcript format.

**Parameters**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| title | string | yes | — | Descriptive title for this session dump |
| project | string | no | — | Override the auto-detected project name |
| session_id | string | no | generated | Stable session identifier supplied by the host |
| source | string | no | `mcp` | Host source: `claude`, `opencode`, `pi`, `codex`, `grok`, `jcode`, `omp`, `cursor`, or `mcp` |
| messages | array | no | — | Explicit `{ role, content, timestamp? }` messages. Required when the host has no native transcript adapter. |
| skip_fabric | boolean | no | true | Skip the fabric Extractor and write a basic summary |

**Returns:** The session ID, source, imported message count, and LoA entry ID when a summary was created.

```js
memory_dump({
  title: "Auth middleware refactor — JWT validation approach",
  project: "my-app",
  source: "codex",
  messages: [
    { role: "user", content: "Refactor the auth middleware" },
    { role: "assistant", content: "Implemented JWT validation" }
  ]
})
```

`memory_dump` is an explicit operation, not lifecycle auto-capture. MCP has no portable event contract for session stop, session start, or pre-compaction.

Message scrubbing follows the shared [Session Dump contract](https://recall.edheltzel.codes/docs/reference/cli/#session-dump). Inside omp, use the native [`recall_dump` tool](https://recall.edheltzel.codes/docs/integrations/omp/#explicit-dump-recall_dump-tool) for the live branch.

When `session_id` already belongs to lifecycle capture, a dump from the same source is supplemental: Recall preserves lifecycle-owned rows and their automatic summary. A conflicting source is rejected rather than taking over the session.

---

## decision_update

Update the status of an existing decision. Use this to mark decisions as superseded (replaced by a newer decision) or reverted (rolled back because it was wrong).

**Parameters**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| id | number | yes | — | Decision ID to update |
| action | string | yes | — | Status transition: `"supersede"` or `"revert"` |

**Returns:** Confirmation with the updated decision's id and new status.

```js
decision_update({ id: 42, action: "supersede" })
decision_update({ id: 17, action: "revert" })
```

---

## When to Use Each Tool

| Scenario | Tool |
|----------|------|
| Starting a new session | `memory_recall` |
| User asks about past work | `memory_search` or `memory_hybrid_search` |
| Before spawning a sub-agent | `context_for_agent` |
| Recording an architectural decision | `memory_add` with `type: "decision"` |
| Capturing a technical insight | `memory_add` with `type: "learning"` |
| Marking work-in-progress state | `memory_add` with `type: "breadcrumb"` |
| Marking a decision as replaced or rolled back | `decision_update` |
| End of session | `memory_dump` |
| Viewing an LoA entry | `loa_show` |
| Quick database health check | `memory_stats` |

Source: https://recall.edheltzel.codes/docs/reference/mcp-tools/index.mdx