Reference

MCP tools

knowmind exposes ten MCP tools over JSON-RPC 2.0 at https://knowmind.de/api/mcp/v1. This reference documents each signature, every parameter, the return schema, a complete example and the typical error cases. MCP protocol version: 2025-06-18.

General

Endpoint: POST https://knowmind.de/api/mcp/v1
Authentication: Authorization: Bearer kmt_…
Body: JSON-RPC 2.0 request with method: "tools/call" and parameters in params.arguments.
Response format: JSON-RPC response. With Accept: text/event-stream the endpoint returns Streamable HTTP frames (SSE) — for native custom connectors in Claude.ai and ChatGPT.
Scope model: read is enough for recall and list tools; write for create and maintain; admin for plan-relevant actions. Scopes are enforced server-side per tool call.
Tenant isolation: a token belongs to exactly one workspace. Cross-tenant access is blocked at the database level.

knowmind.recall

Scope: readsince 0.3.0

Hybrid recall against the Memory Store of your workspace. Combines full-text (BM25 with German analyzer), vector search (multilingual-e5-large, 1024 dimensions) and graph hops in the Knowledge Graph. Cross-encoder rerank for the top hits.

Parameters

Name	Type	Required	Default	Note
query	string	yes	—	Natural-language question
k	integer	no	5	Number of hits (1 to 25)
hops	integer	no	2	Graph-hop depth (0 to 3)

Example — request

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "knowmind.recall",
    "arguments": {
      "query": "Who is the onboarding contact?",
      "k": 5,
      "hops": 2
    }
  }
}

Example — response

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "hits": [
      {
        "memory_id": "memory_onboarding_2026_03",
        "title": "Onboarding contacts Q2 2026",
        "content": "Anna Müller owns onboarding for new service staff, deputised by Tomasz Kowalski.",
        "score": 0.93,
        "source": "internal-handbook-v3"
      }
    ],
    "elapsed_ms": 187
  }
}

Error cases

Code	Meaning
-32602	Invalid params (query missing or empty)
-32000	Service-token unconfigured or provider error
401	Bearer token missing or invalid
429	Rate limit exceeded

knowmind.recall_at_time

Scope: readsince 0.3.0

Point-in-time recall (bi-temporal). Returns only memories that were valid at the given time — i.e. valid_from <= as_of AND (valid_to > as_of OR valid_to is unset). Suitable for "What did the Memory Store know on 14 March?".

Parameters

Name	Type	Required	Default	Note
query	string	yes	—	Natural-language question
as_of	string (ISO 8601)	no	now	Validity point, e.g. 2026-03-14T00:00:00Z
k	integer	no	5	Number of hits (1 to 25)

Example — request

json

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "knowmind.recall_at_time",
    "arguments": {
      "query": "Müller GmbH plan status",
      "as_of": "2026-03-14T00:00:00Z",
      "k": 3
    }
  }
}

Example — response

json

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "hits": [
      {
        "memory_id": "memory_mueller_plan_v2",
        "title": "Müller GmbH plan as of 2026-02-01",
        "content": "Müller GmbH is on Business with five seats.",
        "valid_from": "2026-02-01T00:00:00Z",
        "valid_to": "2026-04-01T00:00:00Z",
        "score": 0.88
      }
    ]
  }
}

Error cases

Code	Meaning
-32602	Invalid params (query missing, as_of not ISO 8601)
401	Bearer token missing or invalid

knowmind.list_relations

Scope: readsince 0.3.0

Returns all inbound and outbound typed relations for a memory. Per relation: type, source and target node, creation time.

Parameters

Name	Type	Required	Default	Note
memory_id	string	yes	—	ID of the memory whose relations to fetch

Example — request

json

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "knowmind.list_relations",
    "arguments": { "memory_id": "memory_workshop_2026_03_12" }
  }
}

Example — response

json

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "outgoing": [
      { "rel_type": "FOR_CLIENT", "to": "memory_mueller_client" },
      { "rel_type": "REFERENCES", "to": "memory_qm_handbook" }
    ],
    "incoming": [
      { "rel_type": "SUPERSEDES", "from": "memory_workshop_2026_03_19" }
    ]
  }
}

Error cases

Code	Meaning
-32602	Invalid params (memory_id missing)
404	Memory not found

knowmind.health

Scope: —since 0.1.0

Returns service status. Reachable with any token. No tenant data.

Parameters

Name	Type	Required	Default	Note
No parameters

Example — request

json

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": { "name": "knowmind.health", "arguments": {} }
}

Example — response

json

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "status": "ok",
    "service": "memory",
    "version": "0.3.0"
  }
}

Error cases

Code	Meaning
503	Service unavailable (memory service, Postgres or graph)

knowmind.stats

Scope: readsince 0.2.0

Current corpus statistics for the token's workspace: number of memories, number of relations, number of chunks in the vector index.

Parameters

Name	Type	Required	Default	Note
No parameters

Example — request

json

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": { "name": "knowmind.stats", "arguments": {} }
}

Example — response

json

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "memories": 1219,
    "edges": 5512,
    "chunks": 3214
  }
}

Error cases

Code	Meaning
401	Bearer token missing or invalid

knowmind.store_memory

Scope: writesince 0.2.0

Creates a new memory in the workspace. If the content is longer than a single section, prefer knowmind.upload_document — it produces chunks and multiple vectors.

Parameters

Name	Type	Required	Default	Note
title	string	no	—	Short title
content	string	yes	—	Full text
memory_type	string (enum)	no	semantic	semantic, episodic, procedural, reference
tags	string[]	no	—	Tags for filtering
source	string	no	—	Source, free text

Example — request

json

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "knowmind.store_memory",
    "arguments": {
      "title": "QM training mandatory",
      "content": "All service staff complete the QM training annually.",
      "memory_type": "procedural",
      "tags": ["qm","training"],
      "source": "internal-handbook"
    }
  }
}

Example — response

json

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "memory_id": "memory_qm_mandatory_2026_05",
    "created_at": "2026-05-23T11:42:08Z"
  }
}

Error cases

Code	Meaning
-32602	Invalid params (content missing, memory_type out of enum)
402	Plan limit reached (e.g. 100 memories on Private)
403	Scope write missing

knowmind.upload_document

Scope: writesince 0.2.0

Ingests a longer text as a document. knowmind splits the text into semantic sections, generates an embedding per section, and creates a document memory linked to its sections via HAS_CHUNK.

Parameters

Name	Type	Required	Default	Note
title	string	no	—	Document title
content	string	yes	—	Full document text
source	string	no	—	Source reference (URL, path)

Example — request

json

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "knowmind.upload_document",
    "arguments": {
      "title": "Onboarding Handbook v3",
      "content": "Chapter 1 — Onboarding flow …",
      "source": "internal-handbook-v3.md"
    }
  }
}

Example — response

json

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "document_id": "doc_onboarding_v3_2026_05",
    "chunks": 23,
    "status": "indexed"
  }
}

Error cases

Code	Meaning
-32602	Invalid params (content missing)
402	Plan limit reached
413	Content too large (> 10 MB)

knowmind.update_fact

Scope: writesince 0.3.0

Bi-temporal update of an existing memory: the original gets valid_to = now, a new version with valid_from = now is created and linked via SUPERSEDES. The history stays auditable — old statements are not deleted, they are marked superseded.

Parameters

Name	Type	Required	Default	Note
target_id	string	yes	—	ID of the memory to update
new_title	string	yes	—	Title of the new version
new_content	string	yes	—	Content of the new version
update_reason	string	no	—	Reason, e.g. "Address changed"

Example — request

json

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "knowmind.update_fact",
    "arguments": {
      "target_id": "memory_mueller_address_v1",
      "new_title": "Müller GmbH address from 2026-06-01",
      "new_content": "Müller GmbH, Industriestraße 7, 32756 Detmold.",
      "update_reason": "Address changed effective 2026-06-01"
    }
  }
}

Example — response

json

{
  "jsonrpc": "2.0",
  "id": 8,
  "result": {
    "old_memory_id": "memory_mueller_address_v1",
    "new_memory_id": "memory_mueller_address_v2",
    "supersedes_edge": "edge_supersedes_2026_05_23"
  }
}

Error cases

Code	Meaning
-32602	Invalid params (required field missing)
404	target_id not found
403	Scope write missing

knowmind.link

Scope: writesince 0.3.0

Creates a typed relation between two memories. The inverse edge is materialised automatically. See the edge-types reference for the allowed types.

Parameters

Name	Type	Required	Default	Note
from_id	string	yes	—	Memory ID of the source node
to_id	string	yes	—	Memory ID of the target node
rel_type	string	yes	—	Edge type in UPPER_SNAKE_CASE (e.g. OWNS, FOR_CLIENT, SUPERSEDES)

Example — request

json

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "knowmind.link",
    "arguments": {
      "from_id": "memory_workshop_2026_03_12",
      "to_id":   "memory_mueller_client",
      "rel_type": "FOR_CLIENT"
    }
  }
}

Example — response

json

{
  "jsonrpc": "2.0",
  "id": 9,
  "result": {
    "edge_id": "edge_for_client_2026_05_23",
    "inverse_edge_id": "edge_has_workshop_2026_05_23"
  }
}

Error cases

Code	Meaning
-32602	Invalid params
400	SHACL constraint violated (e.g. rel_type not allowed for the domain)
404	from_id or to_id not found

knowmind.unlink

Scope: writesince 0.3.0

Deletes a typed relation between two memories. The inverse edge is deleted too.

Parameters

Name	Type	Required	Default	Note
from_id	string	yes	—	Memory ID of the source node
to_id	string	yes	—	Memory ID of the target node
rel_type	string	yes	—	Edge type

Example — request

json

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "knowmind.unlink",
    "arguments": {
      "from_id": "memory_workshop_2026_03_12",
      "to_id":   "memory_mueller_client",
      "rel_type": "FOR_CLIENT"
    }
  }
}

Example — response

json

{
  "jsonrpc": "2.0",
  "id": 10,
  "result": { "deleted": true }
}

Error cases

Code	Meaning
404	Relation not found

General

knowmind.recall

Parameters

Example — request

Example — response

Error cases

knowmind.recall_at_time

Parameters

Example — request

Example — response

Error cases

knowmind.list_relations

Parameters

Example — request

Example — response

Error cases

knowmind.health

Parameters

Example — request

Example — response

Error cases

knowmind.stats

Parameters

Example — request

Example — response

Error cases

knowmind.store_memory

Parameters

Example — request

Example — response

Error cases

knowmind.upload_document

Parameters

Example — request

Example — response

Error cases

knowmind.update_fact

Parameters

Example — request

Example — response

Error cases

knowmind.link

Parameters

Example — request

Example — response

Error cases

knowmind.unlink

Parameters

Example — request

Example — response

Error cases

Related