knowmind exposes 15 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. For the content you query, the database checks on every query which workspace a row belongs to.
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 a search in the Knowledge Graph. Cross-encoder rerank for the top hits. The response starts with the field kein_belastbarer_treffer. When it is true, the corpus most likely holds no answer to the question; the field hinweis says so, and the hits are still included. The flag is an estimate from the rerank score and the coverage of the query terms, not proof.
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
Accepted (0 to 3); currently has no effect on recall.
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"kein_belastbarer_treffer": false,
"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
-32004
Question limit reached — the waiting time is in message
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?". Here too kein_belastbarer_treffer comes first, judged on the hits visible at as_of.
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"kein_belastbarer_treffer": false,
"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)
-32004
Question limit reached — the waiting time is in message
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.
Lists relations that wait for a decision: relations knowmind inferred from text (reason inferred_from_text) and relations that start from a document although their kind needs a person, organisation or similar (reason starts_from_document). Per relation: edge_id, type, state (open, confirmed, rejected), reason, both entries, the source (for example the extraction) and the evidence entry; plus the counts per state. The derivation rules use an open relation only after it is confirmed.
Parameters
Name
Type
Required
Default
Note
status
string
no
—
open, confirmed or rejected; without it all states
Records a decision on one inferred relation. confirm: the derivation rules use the relation from now on. reject: the relation, its reverse relation and every relation derived from it get valid_to; nothing is deleted. undo: takes a rejection back, together with the reverse and derived relations. Returns the state before and after and the number of reverse and derived relations affected.
Lists the most recently created documents and memories of the workspace, sorted by creation date descending (created_at). Source is the document corpus — the same base that recall searches. Graph entities without timestamps do not appear; the count therefore intentionally differs from knowmind_stats (memories).
Creates a new memory persistently in the workspace: Postgres document, vector index and graph node. The entry is then findable via knowmind_recall and knowmind_list_recent. Append-only: entries with the same title are NOT replaced — versioning is handled by knowmind_update_fact. Sha-identical content is detected idempotently (response field unchanged). For longer texts with upsert-by-title, use knowmind_upload_document.
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"
}
}
}
content_required (content missing or empty), too_large (content over 1,000,000 characters), ingest_failed (memory service error — no success is faked, the entry stays marked failed)
401
Bearer token missing or invalid
knowmind_upload_document
Scope: writesince 0.2.0
Ingests a longer text persistently as a document. knowmind splits the text into sections, generates an embedding per section, and creates a graph node. Upsert-by-title (server default): if a document with the same title exists in the same domain, the new version supersedes the old one. The old version stays retrievable for earlier dates via knowmind_recall_at_time; nothing is deleted. The superseded IDs are returned in replaced_document_ids. If the same text already exists in another valid document of the same domain, knowmind creates no new one; the response returns that document's ID in memory_id and carries deduplicated.
Parameters
Name
Type
Required
Default
Note
title
string
no
—
Document title
content
string
yes
—
Full document text
source
string
no
—
Origin (URL, path); does not decide which document is superseded
replace
boolean
no
true
false creates a new document next to the one with the same title
content_required (content missing or empty), too_large (content over 1,000,000 characters), ingest_failed (memory service error)
401
Bearer token missing or invalid
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.
Ends an entry that no longer applies and that nothing replaces, for example after a project closed or a source was withdrawn. The entry gets valid_to and drops out of knowmind_recall; knowmind_recall_at_time still finds it at an earlier time. Nothing is deleted and no new entry is created. Calling it again changes nothing.
Parameters
Name
Type
Required
Default
Note
target_id
string
yes
—
ID of the entry, from knowmind_recall
valid_to
string
no
—
Time with time zone from which the entry no longer applies; defaults to now
Creates the node for a thing the corpus talks about — a person, an organisation, an application, a host, a technology — or returns the existing one. Same name, same class and same workspace always return the same ID; calling twice creates no duplicate. Connect the node afterwards with knowmind_link.
Parameters
Name
Type
Required
Default
Note
name
string
yes
—
Proper name, as it would be written in a document. No role, no status, no description.
entity_class
string
yes
—
Class from the catalogue (knowmind_schema → entityClasses), e.g. Person, Organization, Application, Host, Technology
Returns the relation catalogue of the workspace: every allowed relation with its subject and object classes and an explanation of when it fits, plus the classes for knowmind_entity. Call it before knowmind_link so the right relation is chosen.
