knowmindknowmind
DokumentationQuickstartAnbindungReferenzFehlerbehebung
DEEN
knowmindknowmind
DocumentationQuickstartIntegrationsReferenceTroubleshooting
DEEN

Tasks

Manage relationships

Memories can be linked through typed relationships. A relationship carries a fixed type such as REFERENCES_ENTITY, SUPERSEDES or FOR_CLIENT and makes the knowledge graph traversable. This page shows how to create, inspect and remove them.

Audience
Power users and developers who want to use the Memory Store as a graph. Not strictly required for pure search use cases — knowmind automatically creates reference relationships from wiki-style links in text.

Prerequisites

  • At least two existing memories with known memory IDs
  • For the MCP and REST paths: API token with scope write (Business API or higher)
  • Overview of the available edge types — see the edge types reference
Note

Inverse relationships are created automatically

Every typed relationship has a defined inverse (for instance OWNS ↔ OWNED_BY). knowmind materializes the inverse on creation — you do not have to create the back-direction separately. On removal, the inverse is removed too.

Steps

  1. 1

    Path 1: implicitly while saving (wiki links)

    When you include tags such as [[ada-lovelace]] or @project-helios in a memory, knowmind automatically creates REFERENCES_ENTITY relationships between the memory and the referenced element. This is the simplest path and needs no manual upkeep.

    Outcome: An edge appears in the knowledge graph between the writing memory and the referenced element. The relationship carries the type REFERENCES_ENTITY with the inverse REFERENCED_BY.

  2. 2

    Path 2: through the MCP client from the AI

    From Claude Code, Claude Desktop or any other MCP client you speak to the AI in natural language. The AI calls knowmind.link:

    text
    > Link the memory "Workshop memo 12 March" with the memory
> "Mueller contract v3" through the FOR_CLIENT relationship.

    The corresponding tool signature:

    json
    {
  "name": "knowmind.link",
  "arguments": {
    "from_id": "memory_workshop_2026_03_12",
    "to_id":   "memory_mueller_contract_v3",
    "rel_type": "FOR_CLIENT"
  }
}

    Outcome: The AI reports the result. The inverse relationship is materialized automatically. On the next recall for a question about the Mueller contract the workshop memo is returned alongside.

  3. 3

    Path 3: directly through the REST API

    For backend integrations without an AI in the middle:

    bash
    # Create a relationship
curl -X POST https://knowmind.de/api/v1/graph/relations/create \
  -H "Authorization: Bearer kmt_…" \
  -H "Content-Type: application/json" \
  -d '{
    "from_id": "memory_workshop_2026_03_12",
    "to_id":   "memory_mueller_contract_v3",
    "rel_type": "FOR_CLIENT"
  }'

# List relationships for a memory
curl -X POST https://knowmind.de/api/v1/graph/relations/list \
  -H "Authorization: Bearer kmt_…" \
  -H "Content-Type: application/json" \
  -d '{ "memory_id": "memory_mueller_contract_v3" }'

# Remove a relationship
curl -X POST https://knowmind.de/api/v1/graph/relations/delete \
  -H "Authorization: Bearer kmt_…" \
  -H "Content-Type: application/json" \
  -d '{
    "from_id": "memory_workshop_2026_03_12",
    "to_id":   "memory_mueller_contract_v3",
    "rel_type": "FOR_CLIENT"
  }'

    Outcome: HTTP 200 with a confirmation payload. If you try to create a relationship with an invalid edge type, the API responds with HTTP 400 and a SHACL constraint message including domain and range.

  4. 4

    Path 4: through the cockpit (planned)

    The graphical relationship editor in the cockpit (list view, detail view with drag-and-drop linking, inline validation against edge types) is in the backlog. As of 2026-05-23: in planning, no fixed release date.

    Until it ships, use path 2 (chat-style through the AI) or path 3 (REST API for scripts and automations).

  5. 5

    Changing a relationship

    Relationships are not editable — they are removed and recreated. To turn a FOR_CLIENT into a SUPERSEDES:

    text
    1. knowmind.unlink   from_id=A   to_id=B   rel_type=FOR_CLIENT
2. knowmind.link     from_id=A   to_id=B   rel_type=SUPERSEDES

    For fact updates (a person moves, a contract renews) do not use knowmind.unlink — call knowmind.update_fact instead, which keeps the bi-temporal history intact. See the bi-temporal history concept.

Verify the result

  • knowmind.list_relations with the source memory ID shows the new relationship with its type and target.
  • A recall with a context-relevant question returns both memories together.
  • In the NeoDash dashboard under Knowledge Graph the edge between the two nodes is visible.

Troubleshooting

Error messageCauseResolution
HTTP 400 invalid_edge_typeEdge type is not defined in the schema or rejected as an invalid Domain/Range combination.Verify edge type and allowed Domain/Range in the reference. Example: FOR_CLIENT expects a Project or Document node as from_id and a Client node as to_id.
HTTP 404 memory_not_foundOne of the two memory IDs does not exist in the active workspace, or a typo in the ID.Look up memory IDs via knowmind.recall or in the dashboard and copy them precisely.
HTTP 403 ForbiddenToken has no write scope. link and unlink require write.Create a token with read and write in the dashboard, or extend the existing token.
knowmind.unlink reports edge_not_found although the relationship was visibleEdge was created in the other direction (inverse). Inverse edges are materialized, but the original type is directional.Use knowmind.list_relations to inspect the exact edge direction and call unlink with that direction.

Related