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

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.

// 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.

Parameters

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

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

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

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

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.

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

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).

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.

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.

Parameters

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

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

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

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. Inside omp, use the native 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

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

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

When to Use Each Tool