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

# Tool Reference

> Complete reference for all Meerkat Recall MCP tools organized by category

This page summarizes the MCP tools by category. Fetch `tools/list` from the
chosen endpoint for the exact current schema, profile visibility, and runtime
readiness gates. The four runtime-control tools are added by the managed API
runtime rather than the core dispatcher. Local file helper tools are identified
separately. Examples use fictional people and organizations.

**Profile legend:** D = Default, A = Agent, M = Maintenance, P = Pipeline, F = Full.
Profile membership does not grant scopes or clearances. Examples show tool
arguments, not complete MCP protocol messages; replace record IDs with results
from your own space.

## Find a tool by task

| Task | Start with |
| - | - |
| Check readiness | [get\_runtime\_status](#get_runtime_status) |
| Submit text evidence | [ingest\_doc\_simple](#ingest_doc_simple) |
| Submit structured source data | [ingest\_source\_simple](#ingest_source_simple) |
| Find related knowledge | [search\_all](#search_all) |
| Read entity context | [get\_entity\_context\_bundle](#get_entity_context_bundle) |
| Read a cited view | [get\_knowledge\_view](#get_knowledge_view) |
| Inspect extraction | [get\_doc\_pipeline\_status](#get_doc_pipeline_status), [list\_assertions](#list_assertions) |
| Review duplicate identities | [list\_identity\_candidates](#list_identity_candidates), [merge\_entities](#merge_entities) |
| Diagnose processing | [list\_work\_items](#list_work_items), [get\_health](#get_health) |

For a sequence with prerequisites and completion checks, follow
[MCP workflows](/recall/mcp/workflows).

***

## Versioned sources and scoped retrieval

All these tools use the explicitly selected named space. Their permission and
record-security checks remain independent of profile membership. Source PUT is
an HTTP operation; retained MCP ingest adapters keep their own input contracts.

### search\_scoped

**Profiles:** D, A, M, F

Search with `query`, optional `limit` (1-50), explicit `ranking_mode`
(`lexical`, `semantic`, `hybrid`), and optional `source_revision_constraints`.
Returns `results`, `coverage`, `partial` and source-backed evidence.
See [scoped retrieval](/recall/guides/searching#search-an-exact-source-revision).

### get\_source\_head

**Profiles:** D, A, M, F

Requires `external_source_id`. Returns current generation, desired/published
revision, lifecycle and cleanup state under `read:source` authorization.

### get\_source\_operation

**Profiles:** D, A, M, F

Requires the original `operation_id`. Returns that durable operation's state
without substituting the current head's outcome.

### retract\_source

**Profiles:** F

Requires `external_source_id`, `expected_generation`; optional `idempotency_key`.
Withdraws source support under `read:source` and `write:source` authorization.

### erase\_source

**Profiles:** F

Uses the same generation-bound arguments as retract. Physical cleanup and the
independent recovery journal govern completion. Ordinary retry cannot recreate
the erased source. See [source lifecycles](/recall/api/sources#versioned-source-ingestion).

## Documents and local ingestion

### search\_docs

**Profiles:** A, M, F

Search documents using semantic search, with lexical fallback when embeddings are unavailable.

| Parameter | Type and requirement | Description |
| - | - | - |
| `query` | string; required | Search query text |
| `k` | integer; optional; default 10 | Number of results to return (max 100) |
| `filters.collection` | string; optional | Filter by collection |
| `filters.include_deleted` | boolean; optional; default false | Include soft-deleted documents |

```json theme={null}
{ "query": "Alex Chen", "k": 10, "filters": { "collection": "notes" } }
```

***

### ingest\_doc

**Profiles:** D, F

Ingest a new document for processing using the full document-shaped body. Meerkat Recall stages a source-backed document and enqueues the source-first pipeline. Prefer `ingest_doc_simple` when you only need title, text/media, collection, and metadata.

| Parameter | Type and requirement | Description |
| - | - | - |
| `doc.title` | string; required | Document title |
| `doc.text` | string; required | Document text content |
| `doc.metadata` | object; optional | Arbitrary metadata (e.g., collection, tags) |
| `doc.source` | string; optional | Source record ID |
| `doc.rendition_key` | string; optional | Idempotency key (auto-generated if omitted) |

```json theme={null}
{
  "doc": {
    "title": "Meeting notes",
    "text": "Alice met Bob on 2026-02-02 to discuss Project Meerkat Recall."
  }
}
```

***

### ingest\_doc\_simple

**Profiles:** D, F

Simplified document ingestion with title, optional text, optional media, and optional metadata. All base fields are auto-generated.

| Parameter | Type and requirement | Description |
| - | - | - |
| `title` | string; required | Document title |
| `text` | string; optional | Document text content or sidecar text for media-backed docs |
| `media` | object\[]; optional | Typed image/video inputs; required when `text` is omitted |
| `collection` | string; optional | Collection name for organization |
| `metadata` | object; optional | Optional metadata object |

```json theme={null}
{ "title": "Test Doc", "text": "Alex Chen founded NeuralFlow", "collection": "demo" }
```

***

### batch\_ingest\_docs

**Profiles:** F

Batch ingest multiple documents and return a job ID for progress tracking.

| Parameter | Type and requirement | Description |
| - | - | - |
| `docs` | array; required | Array of normalized document ingest objects. Each item requires `title` and either non-empty `text` or at least one `media` attachment. |

```json theme={null}
{
  "docs": [
    { "title": "Daily standup", "text": "Status: shipped schema fixes." },
    {
      "title": "Observed frame",
      "text": "Observed suspicious activity in the console",
      "media": [
        { "kind": "image", "media_type": "image/jpeg", "path": "/ingest/frame.jpg" }
      ]
    }
  ]
}
```

***

### get\_doc

**Profiles:** A, M, F

Get a document by ID.

| Parameter | Type and requirement | Description |
| - | - | - |
| `id` | string; required | Document ID |

```json theme={null}
{ "id": "doc:3fa85f64-5717-4562-b3fc-2c963f66afa6" }
```

***

### list\_doc\_chunks

**Profiles:** A, M, F

List all structural nodes (chunks) for a document.

| Parameter | Type and requirement | Description |
| - | - | - |
| `id` | string; required | Document ID |

```json theme={null}
{ "id": "doc:3fa85f64-5717-4562-b3fc-2c963f66afa6" }
```

***

### get\_doc\_chunk

**Profiles:** A, M, F

Get a document node (chunk) by ID.

| Parameter | Type and requirement | Description |
| - | - | - |
| `id` | string; required | Document node ID |

```json theme={null}
{ "id": "doc_node:1c0d6c6f-5e3b-4e7d-9c5c-8c4a8f3b7f2a" }
```

***

### delete\_doc

**Profiles:** F

Soft delete a document.

| Parameter | Type and requirement | Description |
| - | - | - |
| `id` | string; required | Document ID |

```json theme={null}
{ "id": "doc:3fa85f64-5717-4562-b3fc-2c963f66afa6" }
```

***

### restore\_doc

**Profiles:** F

Restore a soft-deleted document.

| Parameter | Type and requirement | Description |
| - | - | - |
| `id` | string; required | Document ID |

```json theme={null}
{ "id": "doc:3fa85f64-5717-4562-b3fc-2c963f66afa6" }
```

***

### extract\_doc

**Profiles:** M, F

Manually replay render/build/extraction preparation for an existing document.
This is a maintenance helper for already-ingested docs, not a primary ingest path.

| Parameter | Type and requirement | Description |
| - | - | - |
| `id` | string; required | Document ID |

```json theme={null}
{ "id": "doc:3fa85f64-5717-4562-b3fc-2c963f66afa6" }
```

***

### get\_doc\_pipeline\_status

**Profiles:** F

Get document pipeline status including chunks, revisions, nodes, and extraction progress.

| Parameter | Type and requirement | Description |
| - | - | - |
| `id` | string; required | Document ID |

```json theme={null}
{ "id": "doc:3fa85f64-5717-4562-b3fc-2c963f66afa6" }
```

***

### list\_doc\_collections

**Profiles:** F

List all document collections in the current space.

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

***

### restamp\_attribution

**Profiles:** F

Compatibility operation for application attribution metadata. Supply at least
one selector (`doc_ids`, `session_id`, or `source_uri_prefix`) and the required
`angel_protectees` array. Selectors are unioned; matching documents receive the
exact replacement list, then derived entity attribution is recomputed from
assertion-linked documents. An empty list clears per-subject attribution.
These metadata fields are not a replacement for ABAC security envelopes.

```json theme={null}
{ "doc_ids": ["doc:550e8400-e29b-41d4-a716-446655440000"], "angel_protectees": ["example-subject"] }
```

Recomputation follows assertion evidence. Attribution introduced only by a
later deduplicated promotion without an evidence row is not reconstructed and
may be removed. Inspect the result before relying on the corrected metadata.

***

### ingest\_file

**Profiles:** F

Read a path on the Meerkat Recall server and ingest its text or media content.
Explicitly mount intended files into a container; the supplied Compose file
does not provide an `/ingest` mount. The similarly named local-helper tool
reads client-side UTF-8 text and has a separate schema.

| Parameter | Type and requirement | Description |
| - | - | - |
| `path` | string; required | File path on disk |
| `source_type` | string; optional | Content type hint (auto-detected from extension) |
| `intake` | object; optional for creation; required for changed content | Explicit `revision_id`, `idempotency_key` and `expected_generation` for replacement |

```json theme={null}
{ "path": "/ingest/doc.md" }
```

A replacement uses the same source identity and preserves its security and subject restrictions. Supply all three fields under `intake` for changed content; Recall does not obtain the latest generation on the caller's behalf. Reusing the original intent key returns its original operation. File identity uses the canonical locator, so equal basenames in different directories remain distinct.

***

### ingest\_directory

**Profiles:** F

Ingest server-visible files in a directory matching a glob pattern. The
local-helper variant instead reads client-side UTF-8 text; do not confuse the
two filesystem boundaries.

| Parameter | Type and requirement | Description |
| - | - | - |
| `path` | string; required | Directory path on disk |
| `pattern` | string; optional | Glob pattern (default: `**/*`) |
| `source_type` | string; optional | Content type hint for all files |
| `intake_by_path` | object; optional | Per-file revision, idempotency key and expected generation, keyed by normalized relative path |

```json theme={null}
{ "path": "/path/to/docs", "pattern": "*.md" }
```

For explicit replacements, use the exact relative paths returned by this tool:

```json theme={null}
{
  "path": "/path/to/docs",
  "pattern": "**/*.md",
  "intake_by_path": {
    "daily/note.md": {
      "revision_id": "notes-v2",
      "idempotency_key": "notes-v2",
      "expected_generation": "opaque-generation-from-prior-receipt"
    }
  }
}
```

The map is limited to 1024 entries and 1,000,000 encoded UTF-8 bytes; each path key is at most 4096 bytes. Keys use forward slashes and must name selected files. Absolute paths, parent/dot segments, repeated separators and backslashes are invalid. The full map is validated before any file is accepted.

Each successful `ingested` entry includes `path`, immutable `doc_id`, its original `operation` and nullable `work_item_id`. Unmapped changed files report a generation conflict. Stable intent keys replay original operations. Batches retain per-item outcomes, but a temporary erasure reservation aborts with retryable `not_ready`; files already accepted remain durable.

***

### ingest\_url

**Profiles:** F

Fetch a URL and ingest its content. Text, image, and video URLs are normalized into the same source-first pipeline.

| Parameter | Type and requirement | Description |
| - | - | - |
| `url` | string; required | HTTP/HTTPS URL to fetch |
| `source_type` | string; optional | Content type hint (overrides response header) |
| `intake` | object; optional for creation; required for changed content | Explicit `revision_id`, `idempotency_key` and `expected_generation` for replacement |

```json theme={null}
{ "url": "https://example.com/doc.txt" }
```

Changed content at the same URL requires `intake.revision_id`, `intake.idempotency_key` and the exact `intake.expected_generation` from the prior receipt. The existing source's security, subjects and provenance are retained and inherited by the generated document/media. URL ingestion requests graph processing; acceptance does not prove publication is complete.

## Entities

### search\_entities

**Profiles:** D, A, M, F

Search for entities by query and filters.

| Parameter | Type and requirement | Description |
| - | - | - |
| `query` | string; optional | Free-text search query |
| `filters.entity_type` | string; optional | Filter by entity type |
| `filters.include_deleted` | boolean; optional; default false | Include soft-deleted entities |
| `limit` | integer; optional; default 50 | Max results (max 100) |
| `cursor` | string; optional | Pagination cursor |

```json theme={null}
{ "query": "Alex Chen", "filters": { "entity_type": "person" }, "limit": 10 }
```

***

### get\_entity

**Profiles:** D, A, M, F

Get a single entity by ID.

| Parameter | Type and requirement | Description |
| - | - | - |
| `id` | string; required | Entity ID |

```json theme={null}
{ "id": "entity:f47ac10b-58cc-4372-a567-0e02b2c3d479" }
```

***

### get\_entity\_with\_relations

**Profiles:** D, F

Get an entity with its outgoing and incoming relationships.

| Parameter | Type and requirement | Description |
| - | - | - |
| `id` | string; required | Entity ID |

```json theme={null}
{ "id": "entity:f47ac10b-58cc-4372-a567-0e02b2c3d479" }
```

***

### create\_entity\_simple

**Profiles:** F

Create an entity with only type and display name. All base fields are auto-generated.

| Parameter | Type and requirement | Description |
| - | - | - |
| `entity_type` | string; required | Entity type (e.g., person, org, topic) |
| `display_name` | string; required | Primary display name |
| `summary` | string; optional | Brief summary |

```json theme={null}
{ "entity_type": "person", "display_name": "Alex Chen", "summary": "Founder of NeuralFlow" }
```

***

### update\_entity

**Profiles:** M, F

Update an entity's fields while preserving its complete `security` object.
Read and write access to both versions is required; ordinary scopes do not
permit reclassification, even when the caller can access both classifications.

| Parameter | Type and requirement | Description |
| - | - | - |
| `id` | string; required | Entity ID |
| `fields` | object; required | Fields to update |

```json theme={null}
{ "id": "entity:f47ac10b-58cc-4372-a567-0e02b2c3d479", "fields": { "summary": "Founder of NeuralFlow" } }
```

***

### delete\_entity

**Profiles:** F

Soft delete an entity.

| Parameter | Type and requirement | Description |
| - | - | - |
| `id` | string; required | Entity ID |

```json theme={null}
{ "id": "entity:f47ac10b-58cc-4372-a567-0e02b2c3d479" }
```

***

### restore\_entity

**Profiles:** F

Restore a soft-deleted entity.

| Parameter | Type and requirement | Description |
| - | - | - |
| `id` | string; required | Entity ID |

```json theme={null}
{ "id": "entity:f47ac10b-58cc-4372-a567-0e02b2c3d479" }
```

***

### batch\_entities

**Profiles:** F

Batch create or update entities. Existing entities require read and write
access and unchanged security metadata, including when restoring deleted
records. Include their current `security` in each replacement. Rejected items
are reported in `failed` and do not update or restore the entity.

| Parameter | Type and requirement | Description |
| - | - | - |
| `items` | array; required | Array of entity objects (each requires `type` and `display_name`) |

```json theme={null}
{
  "items": [
    { "type": "person", "display_name": "Alex Chen", "summary": "Security researcher" }
  ]
}
```

## Living Wiki and source freshness

### create\_wiki\_from\_graph

**Profiles:** M, F

Plan, write, and independently verify wiki articles from the graph. Requires
an explicit `manage:wiki` scope with unrestricted subject scope; wildcard
operation permission is insufficient. The caller delegates service authority
across the selected space, including its security envelopes.

| Parameter | Default | Description |
| - | - | - |
| `max_articles` | `0` | Exhaustive automatic curation, or an explicit cap up to 2000 |
| `article_max_hops` | `1` | Context graph hops, 1-4 |
| `article_max_members` | `250` | Governed members per context, 1-250 |
| `publish` | `true` | Publish only articles that pass evidence and freshness gates |
| `manage` | `true` | Register recurring reconciliation; requires `publish=true` |
| `refresh_interval_minutes` | `360` | Managed reconciliation interval, 5-10080 |
| `writer_model`, `verifier_model` | configured models | Optional model overrides |

A draft-only invocation must disable management explicitly:

```json theme={null}
{ "publish": false, "manage": false, "max_articles": 10 }
```

### compile\_wiki\_article

**Profiles:** M, F

Compile one governed definition with separate writer and verifier calls.
Requires the same explicit `manage:wiki` service authority. `definition_id` is
required; `publish` defaults to false. Optional `writer_model` and
`verifier_model` override configured models. Publication also requires an
approved context plan and a clean freshness/quality receipt.

```json theme={null}
{ "definition_id": "knowledge_view_definition:550e8400-e29b-41d4-a716-446655440000", "publish": false }
```

### stop\_managed\_wiki

**Profiles:** M, F

Call with `{}` to revoke the space's recurring wiki authority and cancel queued
jobs. Requires explicit `manage:wiki` and unrestricted subject scope. An
already running publication may finish, but cannot schedule a successor.
Published articles and immutable history remain available. A later explicit
managed creation grants a new registration.

***

### get\_knowledge\_view

**Profiles:** D, A, M, F

Get or lazily refresh a cited, immutable Living Wiki projection rooted at
exactly one entity, source, or governed graph-view definition. Factual Markdown is backed by a statement-level
support ledger. The result includes the stable view, current revision,
dependencies, citations, freshness, and validation receipts.

| Parameter | Type and requirement | Description |
| - | - | - |
| `entity_id` | string; one root required | Canonical entity ID |
| `source_id` | string; one root required | Canonical source ID |
| `definition_id` | string; one root required | Governed topic, community, or query definition ID |
| `freshness` | string; optional; default `prefer_fresh` | `allow_stale`, `prefer_fresh`, or `required` |
| `limit` | integer; optional; default 25 | Maximum records per projection section (max 100) |

```json theme={null}
{ "entity_id": "entity:f47ac10b-58cc-4372-a567-0e02b2c3d479", "freshness": "required" }
```

***

### rebuild\_knowledge\_view

**Profiles:** M, F

Force publication of a new immutable revision for exactly one entity, source,
or governed graph-view definition
root. This requires write authorization for the selected root record.

| Parameter | Type and requirement | Description |
| - | - | - |
| `entity_id` | string; one root required | Canonical entity ID |
| `source_id` | string; one root required | Canonical source ID |
| `definition_id` | string; one root required | Governed topic, community, or query definition ID |
| `limit` | integer; optional; default 25 | Maximum records per projection section (max 100) |

```json theme={null}
{ "source_id": "source:f47ac10b-58cc-4372-a567-0e02b2c3d479", "limit": 25 }
```

***

### materialize\_knowledge\_views

**Profiles:** M, F

Compile existing Meerkat Recall data into Living Wiki pages without first naming
individual roots. The tool scans bounded, ID-ordered pages of entities,
sources, and graph-view definitions. It applies record-level ABAC, continues
past isolated compilation failures, and returns independent cursors for each
record kind. Repeating a page reuses revisions whose dependency receipts are
unchanged.

| Parameter | Type and requirement | Description |
| - | - | - |
| `include_entities` | boolean; optional; default `true` | Materialize canonical entity roots |
| `include_sources` | boolean; optional; default `true` | Materialize canonical source roots |
| `include_definitions` | boolean; optional; default `true` | Materialize governed topic, community, and query definitions |
| `entity_cursor` | string; optional | Entity cursor returned by the previous call |
| `source_cursor` | string; optional | Source cursor returned by the previous call |
| `definition_cursor` | string; optional | Definition cursor returned by the previous call |
| `limit_per_kind` | integer; optional; default 10 | Maximum roots per included kind (max 100) |
| `view_limit` | integer; optional; default 25 | Maximum related records per compiled page section (max 100) |
| `concurrency` | integer; optional; default 4 | Maximum roots compiled concurrently within one kind (max 8) |

```json theme={null}
{
  "include_entities": true,
  "include_sources": true,
  "include_definitions": true,
  "limit_per_kind": 10,
  "view_limit": 25,
  "concurrency": 4
}
```

***

### get\_knowledge\_view\_definition

**Profiles:** D, A, M, F

Read the typed, bounded selector behind a topic, community, or saved-query
projection.

| Parameter | Type and requirement | Description |
| - | - | - |
| `definition_id` | string; required | `knowledge_view_definition` ID |

***

### upsert\_knowledge\_view\_definition

**Profiles:** M, F

Create or update a governed graph-view definition. Selectors are tagged typed
objects, never raw SurrealQL. Supported selectors are bounded topic traversal,
bounded seeded community traversal, and a safe entity query with optional
entity-type, name/alias, and exact approved-attribute filters.

```json theme={null}
{
  "title": "Rust concepts",
  "selector": {
    "type": "topic",
    "topic": "entity:f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "relation_types": ["includes_concept"],
    "max_hops": 2,
    "max_members": 100
  }
}
```

***

### get\_source\_watch

**Profiles:** D, A, M, F

Read the recurring refresh policy and recent immutable observation receipts for
a source without performing network work.

| Parameter | Type and requirement | Description |
| - | - | - |
| `source_id` | string; required | Canonical source ID |
| `check_limit` | integer; optional; default 10 | Maximum recent receipts (max 100) |

```json theme={null}
{ "source_id": "source:f47ac10b-58cc-4372-a567-0e02b2c3d479", "check_limit": 10 }
```

***

### configure\_source\_watch

**Profiles:** M, F

Create, enable, pause, or reschedule a guarded textual web-source watch. The
minimum interval is 60 seconds and the maximum is 31 days.

| Parameter | Type and requirement | Description |
| - | - | - |
| `source_id` | string; required | Canonical web source ID |
| `interval_seconds` | integer; required | Normal interval between checks |
| `enabled` | boolean; optional; default true | Enable or pause the watch |

```json theme={null}
{ "source_id": "source:f47ac10b-58cc-4372-a567-0e02b2c3d479", "interval_seconds": 3600, "enabled": true }
```

***

### check\_source\_watch

**Profiles:** M, F

Enqueue or reopen the source's idempotent refresh work item for immediate leased
execution. A changed textual representation is staged through source-first
re-ingest and canonical triage. Use `get_source_watch` to inspect the immutable
receipt after the work item completes.

```json theme={null}
{ "source_id": "source:f47ac10b-58cc-4372-a567-0e02b2c3d479" }
```

## Relationships

### relate\_entities

**Profiles:** F

Create a relationship between two entities. Optionally creates an evidence assertion. `weight` becomes confidence. The current handler accepts but does not persist `description`, `properties`, `valid_from`, or `valid_to`; use `update_relationship` for stored fields such as `validity_window`.

| Parameter | Type and requirement | Description |
| - | - | - |
| `from_id` | string; required | Source entity ID |
| `to_id` | string; required | Target entity ID |
| `rel_type` | string; required | Relationship type (e.g., `works_at`, `knows`) |
| `weight` | number; optional | Relationship strength (0.0 to 1.0) |
| `valid_from` | string; optional | When the relationship became valid (ISO 8601) |
| `valid_to` | string; optional | When the relationship ended (ISO 8601) |
| `description` | string; optional | Description of the relationship |
| `properties` | object; optional | Additional properties |
| `evidence_text` | string; optional | Evidence quote supporting the relationship |
| `evidence_source` | string; optional | Evidence source record ID |
| `space_id` | string; optional; default current | Space/tenant ID |

```json theme={null}
{
  "from_id": "entity:550e8400-e29b-41d4-a716-446655440000",
  "to_id": "entity:550e8400-e29b-41d4-a716-446655440001",
  "rel_type": "works_at",
  "weight": 0.9
}
```

***

### upsert\_relationship

**Profiles:** F

Create or update a relationship based on from/to/type composite key. `fields` is merged into the serialized record when a match exists; the creation path currently ignores it. Use `update_relationship` for explicit field changes after creation.

| Parameter | Type and requirement | Description |
| - | - | - |
| `from_id` | string; required | Source entity ID |
| `to_id` | string; required | Target entity ID |
| `rel_type` | string; required | Relationship type |
| `fields` | object; optional | Fields to set/update |

```json theme={null}
{
  "from_id": "entity:550e8400-e29b-41d4-a716-446655440000",
  "to_id": "entity:550e8400-e29b-41d4-a716-446655440001",
  "rel_type": "works_at"
}
```

***

### update\_relationship

**Profiles:** F

Update a relationship's serialized record fields by ID, such as `confidence`, `status`, or `validity_window`. See the [record format](/recall/api/relationships).

| Parameter | Type and requirement | Description |
| - | - | - |
| `id` | string; required | Relationship ID |
| `fields` | object; required | Fields to update |

```json theme={null}
{ "id": "rel:550e8400-e29b-41d4-a716-446655440000", "fields": { "confidence": 0.9 } }
```

***

### delete\_relationship

**Profiles:** F

Soft delete a relationship.

| Parameter | Type and requirement | Description |
| - | - | - |
| `id` | string; required | Relationship ID |

```json theme={null}
{ "id": "rel:550e8400-e29b-41d4-a716-446655440000" }
```

***

### restore\_relationship

**Profiles:** F

Restore a soft-deleted relationship.

| Parameter | Type and requirement | Description |
| - | - | - |
| `id` | string; required | Relationship ID |

```json theme={null}
{ "id": "rel:550e8400-e29b-41d4-a716-446655440000" }
```

***

### batch\_relationships

**Profiles:** F

Batch create relationships.

| Parameter | Type and requirement | Description |
| - | - | - |
| `items` | array; required | Array of relationship objects (each requires `from_id`, `to_id`, `rel_type`) |

```json theme={null}
{
  "items": [
    {
      "from_id": "entity:550e8400-e29b-41d4-a716-446655440000",
      "to_id": "entity:550e8400-e29b-41d4-a716-446655440001",
      "rel_type": "works_at",
      "weight": 0.9
    }
  ]
}
```

## Assertions

### list\_assertions

**Profiles:** A, M, F

List assertions with optional filtering by status, source, or predicate.

| Parameter | Type and requirement | Description |
| - | - | - |
| `status` | string; optional | Filter: `pending`, `resolved`, `partial`, `abstained`, `failed`, `superseded` |
| `source_id` | string; optional | Filter by source ID |
| `predicate` | string; optional | Filter by predicate (raw string) |
| `limit` | integer; optional; default 50 | Max results (max 100) |
| `cursor` | string; optional | Pagination cursor |

```json theme={null}
{ "status": "pending", "limit": 10 }
```

***

### get\_assertion

**Profiles:** A, M, F

Get a single assertion by ID with related source and predicate info.

| Parameter | Type and requirement | Description |
| - | - | - |
| `id` | string; required | Assertion ID |

```json theme={null}
{ "id": "assertion:550e8400-e29b-41d4-a716-446655440000" }
```

***

### search\_assertions

**Profiles:** A, M, F

Search assertions by text query across subject, predicate, and object fields.

| Parameter | Type and requirement | Description |
| - | - | - |
| `query` | string; required | Free-text search query |
| `status` | string; optional | Filter by resolution status |
| `limit` | integer; optional; default 50 | Max results (max 100) |

```json theme={null}
{ "query": "works at", "limit": 10 }
```

## Sources

### ingest\_source

**Profiles:** D, F

Create a source, optionally stage text or media on it, and enqueue source-first
ingestion. `source` must be a complete [Source record](/recall/api/sources#raw-source-record-format), including base fields, `type`, and `hash`. Use `ingest_source_simple` to generate these fields. Optional staged-document fields include
`title`, `text`, `media`, `collection`, `metadata`, and `rendition_key`.
`ingest_mode` accepts `skip`, `metadata`, `retrieval`, or `graph`.

```json theme={null}
{
  "source": {
    "id": "source:550e8400-e29b-41d4-a716-446655440000",
    "space_id": "default",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z",
    "created_by": "example-client",
    "provenance": {},
    "security": {
      "policy_id": "default",
      "level": 0
    },
    "type": "manual",
    "hash": "replace-with-the-source-content-hash",
    "external_id": "example:meeting-1"
  },
  "title": "Example meeting",
  "text": "Alice owns the test plan for Project Cedar.",
  "ingest_mode": "graph"
}
```

### ingest\_source\_simple

**Profiles:** D, F

The simplified form requires `name` and accepts optional `uri`, `source_type`,
and the staged-document and ingest-mode fields above.

```json theme={null}
{
  "name": "Example meeting",
  "source_type": "manual",
  "text": "Alice owns the test plan for Project Cedar.",
  "ingest_mode": "graph"
}
```

### batch\_ingest\_sources

**Profiles:** D, F

Accepts required `items`, an array of `ingest_source` input objects such as the
complete example above. Every item requires its own full `source` record. Inspect
each item's result; queue acceptance is not completed semantic extraction.

### search\_sources

**Profiles:** F

Search for sources by query and filters.

| Parameter | Type and requirement | Description |
| - | - | - |
| `query` | string; optional | Free-text search query |
| `filters.include_deleted` | boolean; optional; default false | Include soft-deleted sources |
| `limit` | integer; optional; default 50 | Max results (max 100) |
| `cursor` | string; optional | Pagination cursor |

```json theme={null}
{ "query": "feed", "filters": { "include_deleted": false }, "limit": 10 }
```

***

### get\_source

**Profiles:** A, M, F

Get a single source by ID.

| Parameter | Type and requirement | Description |
| - | - | - |
| `id` | string; required | Source ID |

```json theme={null}
{ "id": "source:550e8400-e29b-41d4-a716-446655440000" }
```

***

### create\_source

**Profiles:** F

Create a new source record.

| Parameter | Type and requirement | Description |
| - | - | - |
| `source` | object; required | Source record to create |

```json theme={null}
{
  "source": {
    "id": "source:550e8400-e29b-41d4-a716-446655440000",
    "space_id": "default",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z",
    "created_by": "example-client",
    "provenance": {},
    "security": {
      "policy_id": "default",
      "level": 0
    },
    "type": "manual",
    "hash": "replace-with-the-source-content-hash",
    "external_id": "example:meeting-1"
  }
}
```

***

### create\_source\_simple

**Profiles:** F

Create a source with only a name. Hash and base fields are auto-generated.

| Parameter | Type and requirement | Description |
| - | - | - |
| `name` | string; required | Human-readable name |
| `uri` | string; optional | URI for the source |
| `source_type` | string; optional | Source type (e.g., web, email, manual) |

```json theme={null}
{ "name": "My Feed", "uri": "https://example.com/feed.xml" }
```

***

### update\_source

**Profiles:** F

Update a source's fields.

| Parameter | Type and requirement | Description |
| - | - | - |
| `id` | string; required | Source ID |
| `fields` | object; required | Fields to update |

```json theme={null}
{ "id": "source:550e8400-e29b-41d4-a716-446655440000", "fields": { "uri": "https://example.com" } }
```

***

### delete\_source

**Profiles:** F

Soft delete a source.

| Parameter | Type and requirement | Description |
| - | - | - |
| `id` | string; required | Source ID |

```json theme={null}
{ "id": "source:550e8400-e29b-41d4-a716-446655440000" }
```

***

### restore\_source

**Profiles:** F

Restore a soft-deleted source.

| Parameter | Type and requirement | Description |
| - | - | - |
| `id` | string; required | Source ID |

```json theme={null}
{ "id": "source:550e8400-e29b-41d4-a716-446655440000" }
```

## Search

### search\_all

**Profiles:** D, A, M, F

Search across entities, documents, sources, and relationships in a single query. Results are grouped by type.

| Parameter | Type and requirement | Description |
| - | - | - |
| `query` | string; required | Search query text |
| `limit` | integer; optional; default 10 | Max results per type (max 100) |
| `include_deleted` | boolean; optional; default false | Include soft-deleted records |
| `include` | array; optional; default all | Restrict to specific types: `entities`, `docs`, `sources`, `relationships` |

```json theme={null}
{ "query": "Alex Chen Acme", "limit": 10, "include": ["entities", "docs", "relationships"] }
```

## Identity

### get\_entity\_context\_bundle

**Profiles:** D, A, M, F

Get authorized, bounded entity context: incoming/outgoing relationships,
attributes, truth slots, events, assertions, freshness, and statistics. The
historical window filters time-sensitive sections; limits apply per section.

| Parameter | Type and requirement | Description |
| - | - | - |
| `id` | string; required | Entity ID |
| `window` | integer; optional; default 30 | Historical window in days (0-36500) |
| `limit` | integer; optional; default 10 | Maximum items per section (1-100) |

```json theme={null}
{ "id": "entity:550e8400-e29b-41d4-a716-446655440000", "window": 30, "limit": 10 }
```

***

### propose\_identity\_candidate

**Profiles:** M, F

Propose two entities as potential duplicates for identity resolution.

| Parameter | Type and requirement | Description |
| - | - | - |
| `candidate.entity_a` | string; required | First entity ID |
| `candidate.entity_b` | string; required | Second entity ID |
| `candidate.confidence` | number; required | Confidence in match (0.0 to 1.0) |
| `candidate.evidence` | string; optional | Evidence or reasoning |
| `candidate.signal_type` | string; optional | How the match was detected |

```json theme={null}
{
  "candidate": {
    "entity_a": "entity:550e8400-e29b-41d4-a716-446655440000",
    "entity_b": "entity:550e8400-e29b-41d4-a716-446655440001",
    "confidence": 0.92,
    "evidence": "Same name + email",
    "signal_type": "heuristic"
  }
}
```

***

### list\_identity\_candidates

**Profiles:** M, F

List pending entity merge candidates.

| Parameter | Type and requirement | Description |
| - | - | - |
| `filters.status` | string; optional | Filter: `pending`, `approved`, `rejected` |
| `filters.min_confidence` | number; optional | Minimum confidence (0.0 to 1.0) |
| `filters.entity_id` | string; optional | Filter by entity involvement |
| `limit` | integer; optional; default 50 | Max results (max 100) |

```json theme={null}
{ "filters": { "status": "pending", "min_confidence": 0.85 }, "limit": 50 }
```

***

### merge\_entities

**Profiles:** M, F

Merge two entities into one. The survivor entity absorbs the merged entity's relationships.

| Parameter | Type and requirement | Description |
| - | - | - |
| `entity_a` | string; required | First entity ID |
| `entity_b` | string; required | Second entity ID |
| `strategy` | string; optional; default `prefer_newer` | Merge strategy: `prefer_newer`, `prefer_older`, `prefer_a`, `prefer_b` |

```json theme={null}
{
  "entity_a": "entity:550e8400-e29b-41d4-a716-446655440000",
  "entity_b": "entity:550e8400-e29b-41d4-a716-446655440001",
  "strategy": "prefer_newer"
}
```

## Predicates

### list\_predicates

**Profiles:** D, A, M, F

List predicate definitions with optional alias mappings.

| Parameter | Type and requirement | Description |
| - | - | - |
| `status` | string; optional | Filter: `active`, `deprecated` |
| `include_aliases` | boolean; optional; default true | Include alias mappings in output |
| `limit` | integer; optional; default 50 | Max results (max 100) |
| `cursor` | string; optional | Pagination cursor |

```json theme={null}
{ "status": "active", "include_aliases": true, "limit": 50 }
```

***

### get\_predicate

**Profiles:** A, M, F

Get a single predicate by its predicate\_id with optional alias mappings.

| Parameter | Type and requirement | Description |
| - | - | - |
| `predicate_id` | string; required | The predicate identifier (e.g., `works_at`) |
| `include_aliases` | boolean; optional; default true | Include alias mappings |

```json theme={null}
{ "predicate_id": "works_at", "include_aliases": true }
```

***

### register\_predicate

**Profiles:** M, F

Register a new predicate in the predicate registry.

| Parameter | Type and requirement | Description |
| - | - | - |
| `predicate_id` | string; required | Unique predicate identifier (e.g., `works_at`) |
| `description` | string; optional | Description of the predicate's semantics |

```json theme={null}
{ "predicate_id": "works_at", "description": "Subject works for or is employed by object" }
```

***

### propose\_predicate\_alias

**Profiles:** M, F

Propose a new alias mapping for a predicate.

| Parameter | Type and requirement | Description |
| - | - | - |
| `alias_name` | string; required | The alias name to propose |
| `canonical_predicate_id` | string; required | The canonical predicate ID this alias maps to |
| `confidence` | number; optional; default 0.8 | Confidence score for the alias (0.0 to 1.0) |

```json theme={null}
{ "alias_name": "employed_by", "canonical_predicate_id": "works_at", "confidence": 0.9 }
```

***

### validate\_predicate\_proposal

**Profiles:** F

Validate a predicate proposal work artifact.

| Parameter | Type and requirement | Description |
| - | - | - |
| `proposal_id` | string; required | The work\_artifact ID of the proposal to validate |

```json theme={null}
{ "proposal_id": "work_artifact:550e8400-e29b-41d4-a716-446655440000" }
```

***

### approve\_predicate\_proposal

**Profiles:** M, F

Approve a predicate alias proposal from a work artifact, creating an active alias.

| Parameter | Type and requirement | Description |
| - | - | - |
| `proposal_id` | string; required | The work\_artifact ID of the proposal to approve |
| `confidence` | number; optional; default 0.95 | Override confidence score for the created alias |

```json theme={null}
{ "proposal_id": "work_artifact:550e8400-e29b-41d4-a716-446655440000", "confidence": 0.95 }
```

## Events

### add\_timeline\_event

**Profiles:** D, M, F

Create a timeline event with explicit evidence references. Meerkat Recall requires at least one `assertion_refs` or `source_refs` item, so this tool stays provenance-safe instead of creating bare events.

| Parameter | Type and requirement | Description |
| - | - | - |
| `title` | string; required | Event title |
| `summary` | string; optional | Optional event summary |
| `subject_ids` | array; optional; default `[]` | Related entity IDs |
| `assertion_refs` | array; optional; default `[]` | Assertion evidence references |
| `source_refs` | array; optional; default `[]` | Source evidence references |
| `time_start` | string; optional | Event start time (`date-time`) |
| `time_end` | string; optional | Event end time (`date-time`) |
| `time_precision` | string; optional; default `unknown` | One of `exact`, `minute`, `hour`, `day`, `month`, `year`, `unknown` |
| `confidence` | number; optional; default event default | Event confidence override |
| `time_confidence` | number; optional; default event default | Temporal confidence override |
| `status` | string; optional; default `approved` | One of `candidate`, `approved`, `superseded`, `rejected` |
| `metadata` | object; optional | Arbitrary event metadata |

```json theme={null}
{
  "title": "Quarterly planning",
  "source_refs": ["source:550e8400-e29b-41d4-a716-446655440000"],
  "time_start": "2026-04-06T09:00:00Z",
  "time_precision": "minute"
}
```

***

### search\_events

**Profiles:** D, A, M, F

Search domain timeline events in the caller's space.

| Parameter | Type and requirement | Description |
| - | - | - |
| `query` | string; optional | Search query |
| `limit` | integer; optional; default 50 | Max results (max 100) |
| `cursor` | string; optional | Pagination cursor |
| `include_deleted` | boolean; optional; default false | Include deleted events |
| `include_candidates` | boolean; optional; default false | Include candidate-status events |
| `statuses` | array; optional | Filter by status: `candidate`, `approved`, `superseded`, `rejected` |
| `entity_ids` | array; optional | Filter by entity involvement |
| `mode` | string; optional | Match mode: `any` or `all` |

```json theme={null}
{ "query": "launch", "limit": 10, "include_candidates": false }
```

***

### get\_event

**Profiles:** D, A, M, F

Get a single domain event by ID.

| Parameter | Type and requirement | Description |
| - | - | - |
| `id` | string; required | Event ID |
| `include_deleted` | boolean; optional; default false | Include deleted events |

```json theme={null}
{ "id": "event:550e8400-e29b-41d4-a716-446655440000" }
```

***

### list\_recent\_events

**Profiles:** D, A, M, F

List recent domain events for the caller's space, ordered by recency.

| Parameter | Type and requirement | Description |
| - | - | - |
| `limit` | integer; optional; default 20 | Max results (max 200) |
| `include_candidates` | boolean; optional; default false | Include candidate-status events |

```json theme={null}
{ "limit": 20, "include_candidates": false }
```

***

### list\_upcoming\_events

**Profiles:** D, A, M, F

List upcoming domain events within a time window.

Events are ordered by `time_start`. Besides events that start within the window, the result
includes events still in progress (`time_end` at or after now) and day-precision events
dated today. Day-precision events are anchored at 00:00Z of their date and Elephant has no
household timezone, so they stay listed for 24 hours after that anchor; filter the exact
local day on the client.

The page is applied after candidate and authorization filtering. The response carries
`items` and `truncated`, which is true when more visible events existed than were returned.

| Parameter | Type and requirement | Description |
| - | - | - |
| `days` | integer; optional; default 7 | Look-ahead window in days (1-365) |
| `include_candidates` | boolean; optional; default false | Include candidate-status events |
| `limit` | integer; optional; default 50 | Maximum events to return (1-50) |

```json theme={null}
{ "days": 14, "include_candidates": false }
```

## Truth Slots

### list\_truth\_slots

**Profiles:** A, M, F

List truth slots with filtering by subject entity and predicate.

| Parameter | Type and requirement | Description |
| - | - | - |
| `subject_entity_id` | string; optional | Filter by subject entity ID |
| `predicate_id` | string; optional | Filter by predicate ID |
| `stale_only` | boolean; optional; default false | Filter for stale slots only |
| `limit` | integer; optional; default 50 | Max results (max 100) |
| `cursor` | string; optional | Pagination cursor |

```json theme={null}
{ "subject_entity_id": "entity:550e8400-e29b-41d4-a716-446655440000", "predicate_id": "works_at", "limit": 25 }
```

***

### get\_truth\_slot\_history

**Profiles:** F

Get all assertions competing for a truth slot, including conflict group information.

| Parameter | Type and requirement | Description |
| - | - | - |
| `id` | string; required | Truth slot ID |

```json theme={null}
{ "id": "truth_slot:550e8400-e29b-41d4-a716-446655440000" }
```

## Work Items

### list\_work\_items

**Profiles:** P, F

List work queue items with filtering by kind, status, or age.

| Parameter | Type and requirement | Description |
| - | - | - |
| `kind` | string; optional | Filter by kind (e.g., `extract`, `embed`, `promote`) |
| `status` | string; optional | Filter: `pending`, `runnable`, `running`, `done`, `failed`, `cancelled` |
| `min_age_secs` | integer; optional | Filter by minimum age in seconds |
| `limit` | integer; optional; default 50 | Max results (max 100) |
| `cursor` | string; optional | Pagination cursor |

```json theme={null}
{ "status": "failed", "limit": 20 }
```

***

### list\_pending\_work\_items

**Profiles:** P, F

List work items that are pending or runnable (ready to be claimed).

| Parameter | Type and requirement | Description |
| - | - | - |
| `kind` | string; optional | Filter by kind |
| `limit` | integer; optional; default 50 | Max results (max 100) |

```json theme={null}
{ "kind": "extract", "limit": 50 }
```

***

### claim\_work\_item

**Profiles:** P, F

Claim a runnable work item with a lease for processing. The selected space must be explicit. Both `read:work_item` and `write:work_item`, plus clearance for the actual stored work item, are required.

| Parameter | Type and requirement | Description |
| - | - | - |
| `id` | string; required | Work item ID |
| `worker_id` | string; required | Identifier of the claiming worker |
| `lease_duration_secs` | integer; optional; default 300 | Positive lease duration that fits a valid expiration timestamp |

```json theme={null}
{ "id": "work_item:550e8400-e29b-41d4-a716-446655440000", "worker_id": "worker-1", "lease_duration_secs": 300 }
```

The successful tool response contains `data.id`, `status`, `claimed: true`, `worker_id`, `lease_token` and `lease_expires_at`. Save the exact opaque `lease_token` from this claim for completion. A later claim by the same worker has a different token; the worker name does not authorize completion. A concurrent authority change or unavailable claim returns `conflict_generation` and requires reconciliation.

***

### complete\_work\_item

**Profiles:** P, F

Finish the original claimed attempt as success or failure. Both `read:work_item` and `write:work_item`, plus current clearance for the actual stored item, are required.

| Parameter | Type and requirement | Description |
| - | - | - |
| `id` | string; required | Work item ID |
| `lease_token` | string; required | Exact opaque token returned by the original successful claim |
| `success` | boolean; optional; default true | Whether the work item succeeded |
| `error` | string; optional | Error message if failed |

```json theme={null}
{ "id": "work_item:550e8400-e29b-41d4-a716-446655440000", "lease_token": "opaque-token-from-original-claim", "success": true }
```

Missing, null or blank `lease_token` is `invalid_request`. A stale token, worker-name substitute, lost lease or changed observed authority is `conflict_generation`, with `retryable: false`; it cannot finish a successor attempt. A successful result contains `data.id`, terminal `status` and `completed: true`. Repeating completion after the attempt is terminal conflicts. Temporary source erasure refusal remains `not_ready`, with `retryable: true`.

Existing clients must retain and echo the claim token. Recall does not infer a token from the latest stored lease.

***

### retry\_work\_item

**Profiles:** P, F

Retry a failed work item by resetting its status to runnable.

| Parameter | Type and requirement | Description |
| - | - | - |
| `id` | string; required | Work item ID |

```json theme={null}
{ "id": "work_item:550e8400-e29b-41d4-a716-446655440000" }
```

## Spaces

### create\_space

**Profiles:** F

Create a space config record for a new space.

| Parameter | Type and requirement | Description |
| - | - | - |
| `name` | string; required | Space ID/name |
| `config.embedding_provider` | string; optional | Embedding provider (e.g., `fastembed`, `openai`) |
| `config.embedding_model` | string; optional | Embedding model identifier |
| `config.embedding_dims` | integer; optional | Embedding vector dimensions |

```json theme={null}
{ "name": "default", "config": { "embedding_provider": "fastembed", "embedding_model": "bge-small-en-v1.5", "embedding_dims": 384 } }
```

***

### list\_spaces

**Profiles:** D, F

List spaces (space\_config records).

| Parameter | Type and requirement | Description |
| - | - | - |
| `limit` | integer; optional; default 50 | Max results (max 1000) |
| `cursor` | string; optional | Pagination cursor (space\_config record ID) |

```json theme={null}
{ "limit": 50 }
```

***

### get\_space

**Profiles:** D, F

Get space configuration by space\_id.

| Parameter | Type and requirement | Description |
| - | - | - |
| `space_id` | string; required | Space ID |

```json theme={null}
{ "space_id": "default" }
```

***

### update\_space

**Profiles:** F

Update space configuration.

| Parameter | Type and requirement | Description |
| - | - | - |
| `space_id` | string; required | Space ID |
| `config.embedding_provider` | string; optional | Embedding provider |
| `config.embedding_model` | string; optional | Embedding model |
| `config.embedding_dims` | integer; optional | Embedding dimensions |

```json theme={null}
{ "space_id": "default", "config": { "embedding_provider": "openai" } }
```

## Reprocess

### create\_reprocess\_job

**Profiles:** F

Create a reprocessing job to backfill or re-extract sources. Automatically enqueues a work item for execution.

| Parameter | Type and requirement | Description |
| - | - | - |
| `name` | string; required | Job name |
| `reason` | string; optional | Reason for reprocessing |
| `selection_criteria.source_types` | array; optional | Source types to include |
| `selection_criteria.date_from` | string; optional | Date range start (YYYY-MM-DD) |
| `selection_criteria.date_to` | string; optional | Date range end (YYYY-MM-DD) |
| `selection_criteria.extractor_version_before` | string; optional | Extractor version threshold |
| `selection_criteria.predicate_ids` | array; optional | Specific predicate IDs |
| `target_stages` | array; required | Stages such as `re-render`, `rebuild-doc-tree`, `re-extract`, `recommit-artifacts`, and `re-maintain` |
| `priority` | integer; optional; default 0 | Priority (higher runs first) |
| `budget_limit_euros` | number; optional | Budget limit in euros |
| `max_sources_per_day` | integer; optional | Rate limit |

```json theme={null}
{
  "name": "Backfill extraction",
  "selection_criteria": { "source_types": ["web"], "date_from": "2026-01-01" },
  "target_stages": ["re-extract"],
  "priority": 1
}
```

***

### get\_reprocess\_job\_progress

**Profiles:** F

Get reprocessing job status and progress.

| Parameter | Type and requirement | Description |
| - | - | - |
| `id` | string; required | Reprocess job ID |

```json theme={null}
{ "id": "reprocess_job:550e8400-e29b-41d4-a716-446655440000" }
```

## System

### get\_runtime\_status

**Profiles:** D, A, M, F

Get managed-runtime readiness, bootstrap status, and semantic ingest availability.

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

<Note>
  This tool is always available on MCP, including bootstrap mode before storage is configured.
</Note>

***

### initialize\_runtime

**Profiles:** D, M, F (bootstrap mode only)

Initialize Meerkat Recall from bootstrap mode and persist `.elephant/elephant_config.toml`.

| Parameter | Type and requirement | Description |
| - | - | - |
| `runtime_mode` | string; optional | `local_memory`, `shared_memory`, `read_only`, or `maintenance` |
| `ingest_enabled` | boolean; optional | Whether semantic ingest should be enabled |
| `backend` | string; optional | `elephant-db` or `surreal-db` |
| `snapshot_path` | string; optional | Embedded snapshot path |
| `surreal_url` | string; optional | SurrealDB URL |
| `surreal_namespace` | string; optional | Surreal namespace |
| `surreal_database` | string; optional | Surreal database |
| `extractor_provider` | string; optional | Semantic extractor provider |
| `extractor_required` | boolean; optional | Require a real extractor for ingest |
| `extractor_mcp_url` | string; optional | Agentic extractor MCP endpoint |
| `extractor_model` | string; optional | Agentic extractor model |

```json theme={null}
{
  "runtime_mode": "local_memory",
  "backend": "elephant-db",
  "ingest_enabled": true,
  "extractor_provider": "meerkat-agentic",
  "extractor_required": true
}
```

***

### get\_runtime\_config

**Profiles:** D, M, F (configured admin-capable runtimes)

Return the effective runtime configuration with secrets redacted.

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

***

### configure\_runtime

**Profiles:** D, M, F (configured admin-capable runtimes)

Patch the persisted runtime configuration and apply it live.

| Parameter | Type and requirement | Description |
| - | - | - |
| `runtime_mode` | string; optional | `local_memory`, `shared_memory`, `read_only`, or `maintenance` |
| `ingest_enabled` | boolean; optional | Whether semantic ingest should be enabled |
| `backend` | string; optional | `elephant-db` or `surreal-db` |
| `snapshot_path` | string; optional | Embedded snapshot path |
| `surreal_url` | string; optional | SurrealDB URL |
| `surreal_namespace` | string; optional | Surreal namespace |
| `surreal_database` | string; optional | Surreal database |
| `extractor_provider` | string; optional | Semantic extractor provider |
| `extractor_required` | boolean; optional | Require a real extractor for ingest |
| `extractor_mcp_url` | string; optional | Agentic extractor MCP endpoint |
| `extractor_model` | string; optional | Agentic extractor model |

```json theme={null}
{
  "ingest_enabled": false,
  "runtime_mode": "read_only"
}
```

***

### get\_health

**Profiles:** D, A, M, F

Get lightweight system health status, including the active backend and storage state.

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

***

### get\_capabilities

**Profiles:** A, M, F

Get system capabilities and available tools.

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

***

### get\_provenance

**Profiles:** D

<Warning>
  Use only for trusted callers entitled to all content in the selected space.
  The current handler checks scopes and space but does not authorize each
  returned claim or evidence record. It must not serve as a clearance-filtered
  provenance API. See [security boundaries](/recall/concepts/security#authorization-boundaries).
</Warning>

Get provenance chain for a record, tracing its origin through sources and pipeline steps.

| Parameter | Type and requirement | Description |
| - | - | - |
| `id` | string; required | Record ID (any type) |

```json theme={null}
{ "id": "entity:f47ac10b-58cc-4372-a567-0e02b2c3d479" }
```

***

### get\_tool\_schema

**Profiles:** F

Return the full JSON schema for a tool, including required fields and examples.

| Parameter | Type and requirement | Description |
| - | - | - |
| `tool_name` | string; required | Tool name to inspect |

```json theme={null}
{ "tool_name": "ingest_doc" }
```

***

### get\_job\_status

**Profiles:** F

Get the status and progress payload for a job (work item).

| Parameter | Type and requirement | Description |
| - | - | - |
| `job_id` | string; required | Job/work item ID |

```json theme={null}
{ "job_id": "work_item:550e8400-e29b-41d4-a716-446655440000" }
```

***

### export\_snapshot

**Profiles:** M, F

Export the live embedded store to a host path.

| Parameter | Type and requirement | Description |
| - | - | - |
| `path` | string; required | Host filesystem path for the snapshot |

```json theme={null}
{ "path": "/tmp/elephant.json" }
```

<Note>
  This tool only appears when Meerkat Recall is running `ELEPHANT_DB=elephant-db` and the caller qualifies for global snapshot administration.
</Note>

***

### import\_snapshot

**Profiles:** M, F

Replace the live embedded store from a host snapshot.

| Parameter | Type and requirement | Description |
| - | - | - |
| `path` | string; required | Host filesystem path to import |

```json theme={null}
{ "path": "/tmp/elephant.json" }
```

<Warning>
  Snapshot import is a whole-store administrative operation. It is only available on embedded deployments and only to callers that qualify for global snapshot administration.
</Warning>

***

### revert\_audit

**Profiles:** F

Revert changes from an audit log entry.

| Parameter | Type and requirement | Description |
| - | - | - |
| `audit_id` | string; required | Audit log entry ID to revert |

```json theme={null}
{ "audit_id": "audit_log:550e8400-e29b-41d4-a716-446655440000" }
```

***

### stream\_events

**Profiles:** F

Stream system events from a cursor position.

| Parameter | Type and requirement | Description |
| - | - | - |
| `space_id` | string; optional; default `default` | Space ID to stream from |
| `cursor` | string; optional | Cursor position (sequence number) |
| `limit` | integer; optional; default 100 | Max events to return (max 1000) |

```json theme={null}
{ "space_id": "default", "cursor": "0", "limit": 100 }
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.