mnema

Official

Overview Schema Source Related Servers Discussions Admin

Link knowledge

link_knowledge

Creates a directed, labeled edge between a subject and target record, recording the relationship permanently in mnema’s append-only history for later reading.

Instructions

Link one piece of knowledge to another: a directed edge from a subject entity to a target entity, labeled by a relation rel. The relation is an OPEN string (recommended: supersedes, relates-to, derived-from, contradicts, governs, asks-for-a-person, refuses-a-write; any label is accepted). An ADR-<n> label is recorded as the id of the one decision it names, and refused when several carry it or none does. Neither endpoint is checked to exist: a link is legitimately cross-tree, resolved on read. Optionally pick the scope and the project the EDGE is recorded in; omitted, a link asserts a relation between the project’s records and lands PUBLIC (global outside a project). A link has no id of its own: it is an edge. The reply says which tree it landed in. RECORDING IS PERMANENT: mnema is append-only and nothing deletes a fact. A record in the public scope is committed to the repository and reaches every machine that clones it (published, if that repository is public). So do NOT record credentials here. Values in a recognized format (cloud keys, API tokens, private keys, a password inside a URL) are replaced with a typed placeholder before anything is written and the reply says what was replaced, but a format mnema does not recognize is written verbatim and cannot be taken back. Do not record personal data either: an email address is replaced with and reported, and the mnid already says who wrote. Each text field holds at most 65536 bytes; a longer one is refused, not truncated.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "subject": "<subject>",
      "target": "<target>",
      "rel": "<rel>"
    },
    "name": "link_knowledge"
  }
}

Input Schema

Name	Required	Description
`rel`	Yes	The relation label (an open string).
`scope`	No	Where the link lands; overrides the routing rule (public).
`target`	Yes	What the link points at: the id of another record, or, under `governs`, a path in the working tree, relative to the project root.
`project`	No	Which project of this workspace the fact belongs to: its absolute path, as this server gave it; a bare name is refused. Omitted, it lands in the project this session resolved to (the one `bootstrap` names). Pass it whenever the work being recorded happened in a different project of this workspace.
`subject`	Yes	The entity that originates the link.

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 9, 2026

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

This goes well past the annotations (which only say readOnly=false, idempotent=false, destructive=false) by disclosing the properties that actually matter: recording is permanent and append-only, public-scope links are committed to the repository and reach every clone, and a public repo publishes them. It also discloses redaction behavior (recognized credential formats and emails replaced with typed placeholders and reported, unrecognized formats written verbatim and irreversible), the 65536-byte refusal-not-truncation rule, that endpoints are not existence-checked, and that the reply reports which tree the link landed in. No contradiction with the annotations: destructiveHint=false is about not destroying existing data, which is consistent with an append-only insert.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the data model before the safety material, and nearly every sentence carries distinct information (ADR resolution, permanence, redaction, size limit). It is long and the credential warning is stated twice in effect ("So do NOT record credentials here" plus the placeholder explanation), which is slightly redundant, but nothing is padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description still covers the return contract (which tree it landed in, what was replaced). For a non-idempotent, permanent, potentially public write, it supplies the failure modes (ambiguous ADR, oversized field, refused) and the security constraints an agent needs before calling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `rel` is enumerated with recommended labels (supersedes, contradicts, governs, ...), `ADR-<n>` labels are resolved to the single decision they name and refused when ambiguous or missing, and `scope`/`project` are explicitly framed as governing where the EDGE lands rather than its endpoints. That resolves the genuinely confusing question of how a project-scoped edge relates to a cross-tree link.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

"Link one piece of knowledge to another: a directed edge from a `subject` entity to a `target` entity, labeled by a relation `rel`" names a specific verb, both endpoints, and the edge semantics, so an agent knows exactly what this creates versus a record-creating sibling. It further pins down that a link has no id of its own, which is a distinguishing structural fact rather than restatement of the name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage guidance is present but about content, not alternatives: it tells the agent not to record credentials or personal data, and explains the scope/project routing default ("omitted, a link asserts a relation between the project's records and lands PUBLIC"). No sibling is named and there is no explicit statement of when to use link_knowledge rather than capture_memory or record_observation, so the agent must infer the choice. Notably, "nothing deletes a fact" creates an unaddressed tension with the retract_link sibling that the definition never resolves.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.