CPersona

Official

by Cloto-dev

Overview Schema Source Related Servers Discussions Admin

Python

Local

declare_associations

DestructiveIdempotent

Instructions

Declare associative memory after the fact: entities with aliases, and subject–predicate–object relations, recorded verbatim and walked by reconstruct. The server extracts nothing and infers nothing — coverage is exactly what was declared. anchor_ref names the record (mem:<id> / ep:<id>) the declaration is evidenced by: every entity named is recorded as mentioned by it and every relation carries it. Malformed items are reported in dropped and skipped; nothing else in the call is refused for them. retract removes relations by id and mentions by {entity, ref} — the only way a declaration leaves the store. Response: {ok, result:'declared', entities:[{id, name, created}], mentions, relations:[ids], dropped:[{item, reason}], retracted?:{relations, mentions}}. Under pause_persistence nothing is written (result:'skipped', persisted:false).

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": {
      "agent_id": "<agent_id>"
    },
    "name": "declare_associations"
  }
}

Input Schema

Name	Required	Description
`channel`	No	Memory channel the declaration belongs to. Default: '' (shared).
`retract`	No	Declarations to remove: {relations: [relation ids], mentions: [{entity: <entity id>, ref: 'mem:<id>'}]}. Only this agent's rows are touched.
`agent_id`	Yes	Agent identifier
`anchor_ref`	No	The record this declaration is evidenced by: 'mem:<id>' or 'ep:<id>' of this agent. Optional.
`project_id`	No	Project the declaration belongs to. Optional — omit or pass '' for the global pool. v2.5.1: pass '@auto' to resolve this agent's default from the server's operating context, echoed as resolved_project_id. An unmapped agent gets '' with operating_context_warning; enforce='off' omits the warning, and enforce='reject' refuses a write. bug-186: resolution requires a configured operating context. With none (the default, or an unparsable sidecar) '@auto' is NOT resolved: it is stored and filtered as a literal project_id, resolved_project_id echoes '@auto', and no warning is raised. Check resolved_project_id before relying on it.
`session_key`	No	Opaque session identity you declare: a partition hint, not authentication and not a data filter. Selects which no-persist pause applies to this call. Omit to share one bucket with every caller that omits it. Full text on recall.
`associations`	No	The entities and relations to declare. Malformed items are reported in `dropped` and skipped.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv2.6.12Oct 21, 2026

changedInput schema / properties / project_id / description

Previous value: -"Project the declaration belongs to. Optional — omit or pass '' for the global pool. v2.5.1: pass '@auto' to resolve this agent's default from the server's operating context (the resolution is echoed as resolved_project_id; an unmapped agent yields operating_context_warning). bug-186: resolution requires a configured operating context. With none — the default, and equally the outcome of a sidecar that fails to parse — the sentinel is NOT resolved: it is stored and filtered as the literal project_id '@auto', resolved_project_id echoes '@auto', and no warning is raised. Read resolved_project_id before relying on the resolution."New value: +"Project the declaration belongs to. Optional — omit or pass '' for the global pool. v2.5.1: pass '@auto' to resolve this agent's default from the server's operating context, echoed as resolved_project_id. An unmapped agent gets '' with operating_context_warning; enforce='off' omits the warning, and enforce='reject' refuses a write. bug-186: resolution requires a configured operating context. With none (the default, or an unparsable sidecar) '@auto' is NOT resolved: it is stored and filtered as a literal project_id, resolved_project_id echoes '@auto', and no warning is raised. Check resolved_project_id before relying on it."

Changed3 schema fields changedv2.6.1Sep 30, 2026

changedInput schema / properties / associations / description

Previous value: -"Associative memory to declare alongside this call: entities the text mentions, with their aliases, and subject–predicate–object relations. Stored verbatim; the server extracts nothing and infers nothing. On store, the stored memory is recorded as mentioning every entity named here and anchors every relation. Malformed items are reported in the response's associations.dropped and skipped; the memory is stored regardless. Optional."New value: +"The entities and relations to declare. Malformed items are reported in `dropped` and skipped."

changedInput schema / properties / associations / properties / entities / description

Previous value: -"Entities to register (if new) and mark as mentioned. Names are compared after normalization (NFKC, case-folded, whitespace collapsed)."New value: +"Entities to register (if new) and mark as mentioned. Names and aliases are compared after normalization (NFKC, case-folded, whitespace collapsed), so two that normalize alike name one entity."

addedInput schema / properties / session_key / maxLength
```
Added value: +256
```

Addedv2.5.12Sep 20, 2026

TDQS

A4.7/5.0

Behavior5/5

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

The description adds substantial behavioral detail beyond the annotations: nothing is extracted or inferred, coverage equals exactly what was declared, malformed items are dropped and skipped without refusing the call, retract removes relations/mentions, and pause_persistence causes a skipped non-persisted result. This is especially valuable given destructiveHint=true.

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

Conciseness5/5

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

The description is dense but front-loaded: the first sentence establishes purpose, and subsequent sentences cover anchoring, dropping, retraction, response shape, and pause behavior. For a complex nested tool, every part appears to earn its place.

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?

Given the nested schema, destructive/idempotent annotations, and absence of an output schema, the description is complete enough: it explains declaration behavior, malformed-item handling, retraction, response fields, and pause_persistence behavior.

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

Parameters4/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. The description still adds meaning beyond the schema by explaining that anchor_ref makes every named entity mentioned by that record and every relation carry that ref, and by clarifying retract behavior over relations and mentions.

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?

The description states a specific verb and resource: declaring associative memory with entities, aliases, and subject–predicate–object relations. It also clarifies that the declaration is recorded verbatim and later walked by reconstruct, which distinguishes this from traversal/read tools like reconstruct or recall.

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

Usage Guidelines4/5

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

It gives clear usage context: declare associations after the fact, anchor them to a record, and use retract as the only way a declaration leaves the store. It does not explicitly compare against sibling write tools like store, so it stops short of full when-to-use/when-not guidance.

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