Tool Reference - Meerkat

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
Submit text evidence	ingest_doc_simple
Submit structured source data	ingest_source_simple
Find related knowledge	search_all
Read entity context	get_entity_context_bundle
Read a cited view	get_knowledge_view
Inspect extraction	get_doc_pipeline_status, list_assertions
Review duplicate identities	list_identity_candidates, merge_entities
Diagnose processing	list_work_items, get_health

For a sequence with prerequisites and completion checks, follow 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.

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.

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

{ "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)

{
  "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

{ "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.

{
  "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

{ "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

{ "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

{ "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

{ "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

{ "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

{ "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

{ "id": "doc:3fa85f64-5717-4562-b3fc-2c963f66afa6" }

list_doc_collections

Profiles: F List all document collections in the current space.

{}

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.

{ "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

{ "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

{ "path": "/path/to/docs", "pattern": "*.md" }

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

{
  "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

{ "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

{ "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

{ "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

{ "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

{ "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

{ "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

{ "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

{ "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`)

{
  "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:

{ "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.

{ "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)

{ "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)

{ "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)

{
  "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.

{
  "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)

{ "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

{ "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.

{ "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

{
  "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

{
  "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.

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

{ "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

{ "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

{ "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`)

{
  "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

{ "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

{ "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)

{ "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, 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.

{
  "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.

{
  "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

{ "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

{ "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

{
  "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)

{ "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

{ "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

{ "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

{ "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`

{ "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)

{ "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

{
  "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)

{ "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`

{
  "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

{ "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

{ "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

{ "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)

{ "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

{ "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

{ "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

{
  "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`

{ "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

{ "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

{ "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)

{ "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

{ "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

{ "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

{ "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)

{ "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

{ "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

{ "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

{ "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

{ "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)

{ "limit": 50 }

get_space

Profiles: D, F Get space configuration by space_id.

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

{ "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

{ "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

{
  "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

{ "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.

{}

This tool is always available on MCP, including bootstrap mode before storage is configured.

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

{
  "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.

{}

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

{
  "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.

{}

get_capabilities

Profiles: A, M, F Get system capabilities and available tools.

{}

get_provenance

Profiles: D

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.

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)

{ "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

{ "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

{ "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

{ "path": "/tmp/elephant.json" }

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

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

{ "path": "/tmp/elephant.json" }

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.

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

{ "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)

{ "space_id": "default", "cursor": "0", "limit": 100 }

​Find a tool by task

​Versioned sources and scoped retrieval

​search_scoped

​get_source_head

​get_source_operation

​retract_source

​erase_source

​Documents and local ingestion

​search_docs

​ingest_doc

​ingest_doc_simple

​batch_ingest_docs

​get_doc

​list_doc_chunks

​get_doc_chunk

​delete_doc

​restore_doc

​extract_doc

​get_doc_pipeline_status

​list_doc_collections

​restamp_attribution

​ingest_file

​ingest_directory

​ingest_url

​Entities

​search_entities

​get_entity

​get_entity_with_relations

​create_entity_simple

​update_entity

​delete_entity

​restore_entity

​batch_entities

​Living Wiki and source freshness

​create_wiki_from_graph

​compile_wiki_article

​stop_managed_wiki

​get_knowledge_view

​rebuild_knowledge_view

​materialize_knowledge_views

​get_knowledge_view_definition

​upsert_knowledge_view_definition

​get_source_watch

​configure_source_watch

​check_source_watch

​Relationships

​relate_entities

​upsert_relationship

​update_relationship

​delete_relationship

​restore_relationship

​batch_relationships

​Assertions

​list_assertions

​get_assertion

​search_assertions

​Sources

​ingest_source

​ingest_source_simple

​batch_ingest_sources

​search_sources

​get_source

​create_source

​create_source_simple

​update_source

​delete_source

​restore_source

​Search

​search_all

​Identity

​get_entity_context_bundle

​propose_identity_candidate

​list_identity_candidates

​merge_entities

​Predicates

​list_predicates

​get_predicate

​register_predicate

​propose_predicate_alias

​validate_predicate_proposal

Find a tool by task

Versioned sources and scoped retrieval

search_scoped

get_source_head

get_source_operation

retract_source

erase_source

Documents and local ingestion

search_docs

ingest_doc

ingest_doc_simple

batch_ingest_docs

get_doc

list_doc_chunks

get_doc_chunk

delete_doc

restore_doc

extract_doc

get_doc_pipeline_status

list_doc_collections

restamp_attribution

ingest_file

ingest_directory

ingest_url

Entities

search_entities

get_entity

get_entity_with_relations

create_entity_simple

update_entity

delete_entity

restore_entity

batch_entities

Living Wiki and source freshness

create_wiki_from_graph

compile_wiki_article

stop_managed_wiki

get_knowledge_view

rebuild_knowledge_view

materialize_knowledge_views

get_knowledge_view_definition

upsert_knowledge_view_definition

get_source_watch

configure_source_watch

check_source_watch

Relationships

relate_entities

upsert_relationship

update_relationship

delete_relationship

restore_relationship

batch_relationships

Assertions

list_assertions

get_assertion

search_assertions

Sources

ingest_source

ingest_source_simple

batch_ingest_sources

search_sources

get_source

create_source

create_source_simple

update_source

delete_source

restore_source

Search

search_all

Identity

get_entity_context_bundle

propose_identity_candidate

list_identity_candidates

merge_entities

Predicates

list_predicates

get_predicate

register_predicate

propose_predicate_alias

validate_predicate_proposal