Skip to main content
Glama

Associate Memories

associate_memories
Idempotent

Create typed relationships between memories to build a knowledge graph, improving recall by surfacing related context; link single pairs or up to 500 associations in batch.

Instructions

Create typed relationships between memories. This builds a knowledge graph that improves recall by surfacing related context. Supports single-pair mode or batch mode with associations[] (max 500).

When to use:

  • After storing a new memory: link it to related existing memories

  • When a bug fix relates to an original feature implementation

  • When a new decision updates or invalidates a previous one

  • To connect patterns with their concrete examples

Authorable relationship types:

  • RELATES_TO: General relationship (default)

  • LEADS_TO: Causal relationship (A caused B)

  • OCCURRED_BEFORE: Temporal ordering

  • PREFERS_OVER: Chosen alternative

  • EXEMPLIFIES: Concrete example of a pattern

  • CONTRADICTS: Conflicts with another memory

  • REINFORCES: Strengthens another memory's validity

  • INVALIDATED_BY: Superseded by another memory

  • EVOLVED_INTO: Updated version of a concept

  • DERIVED_FROM: Implementation of a decision/pattern

  • PART_OF: Component of a larger effort

Read-only/internal relations:

  • System/internal relations such as SIMILAR_TO, PRECEDED_BY, EXPLAINS, SHARES_THEME, PARALLEL_CONTEXT, and DISCOVERED may appear in recall results, but they are not valid inputs for associate_memories.

Examples:

  • associate_memories({ memory1_id: "8f3a2c1e-5b7d-4e9a-a1c3-2d4f6b8e0a91", memory2_id: "3c9e7b2a-1f4d-4a8e-9b6c-5d2e8f1a7c34", type: "RELATES_TO", strength: 0.9 }) // bug fix → feature

  • associate_memories({ memory1_id: "3c9e7b2a-1f4d-4a8e-9b6c-5d2e8f1a7c34", memory2_id: "8f3a2c1e-5b7d-4e9a-a1c3-2d4f6b8e0a91", type: "EVOLVED_INTO", strength: 0.8 }) // old decision → new

  • associate_memories({ associations: [{ memory1_id: "8f3a2c1e-5b7d-4e9a-a1c3-2d4f6b8e0a91", memory2_id: "3c9e7b2a-1f4d-4a8e-9b6c-5d2e8f1a7c34", type: "RELATES_TO", strength: 0.8 }] })

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "associate_memories"
  }
}

Input Schema

NameRequiredDescriptionDefault
roleNoPART_OF only.
typeNo
reasonNoPREFERS_OVER, CONTRADICTS, INVALIDATED_BY or EVOLVED_INTO only.
contextNoPREFERS_OVER or PART_OF only.
strengthNo0.9+ direct causation, 0.7-0.9 strong, 0.5-0.7 moderate
timestampNoINVALIDATED_BY only.
confidenceNoEXEMPLIFIES, EVOLVED_INTO or DERIVED_FROM only.
memory1_idNoSource memory ID
memory2_idNoTarget memory ID
resolutionNoCONTRADICTS only.
associationsNoBatch mode. Do not combine with top-level memory1_id/memory2_id/type/strength.
observationsNoREINFORCES only.
pattern_typeNoEXEMPLIFIES only: pattern label.
transformationNoDERIVED_FROM only.

Output Schema

NameRequiredDescriptionDefault
failedNoBatch mode.
messageYes
successYesFalse when any batch item failed.
summaryNoBatch mode.
succeededNoBatch mode.
failed_countNoBatch mode.
created_countNoBatch mode.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed34 schema fields changedv0.14.4
    • changedInput schema / properties / associations / description
      Previous value: -"Batch mode. Up to 500 associations. Do not combine with top-level memory1_id/memory2_id/type/strength."New value: +"Batch mode. Do not combine with top-level memory1_id/memory2_id/type/strength."
    • changedInput schema / properties / associations / items / properties / confidence / description
      Previous value: -"Relation-specific confidence for EXEMPLIFIES, EVOLVED_INTO, or DERIVED_FROM."New value: +"EXEMPLIFIES, EVOLVED_INTO or DERIVED_FROM only."
    • changedInput schema / properties / associations / items / properties / context / description
      Previous value: -"Relation-specific context for PREFERS_OVER or PART_OF associations."New value: +"PREFERS_OVER or PART_OF only."
    • removedInput schema / properties / associations / items / properties / memory1_id / description
      Removed value: -"ID of the source memory"
    • removedInput schema / properties / associations / items / properties / memory2_id / description
      Removed value: -"ID of the target memory"
    • changedInput schema / properties / associations / items / properties / observations / description
      Previous value: -"Relation-specific observations for REINFORCES associations."New value: +"REINFORCES only."
    • changedInput schema / properties / associations / items / properties / pattern_type / description
      Previous value: -"Relation-specific pattern label for EXEMPLIFIES associations."New value: +"EXEMPLIFIES only: pattern label."
    • changedInput schema / properties / associations / items / properties / reason / description
      Previous value: -"Relation-specific reason for PREFERS_OVER, CONTRADICTS, INVALIDATED_BY, or EVOLVED_INTO associations."New value: +"PREFERS_OVER, CONTRADICTS, INVALIDATED_BY or EVOLVED_INTO only."
    • changedInput schema / properties / associations / items / properties / resolution / description
      Previous value: -"Relation-specific resolution for CONTRADICTS associations."New value: +"CONTRADICTS only."
    • changedInput schema / properties / associations / items / properties / role / description
      Previous value: -"Relation-specific role for PART_OF associations."New value: +"PART_OF only."
    • removedInput schema / properties / associations / items / properties / strength / description
      Removed value: -"Relationship strength from 0 to 1"
    • changedInput schema / properties / associations / items / properties / timestamp / description
      Previous value: -"Relation-specific timestamp for INVALIDATED_BY associations."New value: +"INVALIDATED_BY only."
    • changedInput schema / properties / associations / items / properties / transformation / description
      Previous value: -"Relation-specific transformation note for DERIVED_FROM associations."New value: +"DERIVED_FROM only."
    • removedInput schema / properties / associations / items / properties / type / description
      Removed value: -"Relationship type between the two memories"
    • changedInput schema / properties / confidence / description
      Previous value: -"Relation-specific confidence for EXEMPLIFIES, EVOLVED_INTO, or DERIVED_FROM."New value: +"EXEMPLIFIES, EVOLVED_INTO or DERIVED_FROM only."
    • changedInput schema / properties / context / description
      Previous value: -"Relation-specific context for PREFERS_OVER or PART_OF associations."New value: +"PREFERS_OVER or PART_OF only."
    • changedInput schema / properties / memory1_id / description
      Previous value: -"ID of the source memory (from store_memory response or recall results)"New value: +"Source memory ID"
    • changedInput schema / properties / memory2_id / description
      Previous value: -"ID of the target memory to link to"New value: +"Target memory ID"
    • changedInput schema / properties / observations / description
      Previous value: -"Relation-specific observations for REINFORCES associations."New value: +"REINFORCES only."
    • changedInput schema / properties / pattern_type / description
      Previous value: -"Relation-specific pattern label for EXEMPLIFIES associations."New value: +"EXEMPLIFIES only: pattern label."
    • changedInput schema / properties / reason / description
      Previous value: -"Relation-specific reason for PREFERS_OVER, CONTRADICTS, INVALIDATED_BY, or EVOLVED_INTO associations."New value: +"PREFERS_OVER, CONTRADICTS, INVALIDATED_BY or EVOLVED_INTO only."
    • changedInput schema / properties / resolution / description
      Previous value: -"Relation-specific resolution for CONTRADICTS associations."New value: +"CONTRADICTS only."
    • changedInput schema / properties / role / description
      Previous value: -"Relation-specific role for PART_OF associations."New value: +"PART_OF only."
    • changedInput schema / properties / strength / description
      Previous value: -"Relationship strength: 0.9+ direct causation, 0.7-0.9 strong relation, 0.5-0.7 moderate"New value: +"0.9+ direct causation, 0.7-0.9 strong, 0.5-0.7 moderate"
    • changedInput schema / properties / timestamp / description
      Previous value: -"Relation-specific timestamp for INVALIDATED_BY associations."New value: +"INVALIDATED_BY only."
    • changedInput schema / properties / transformation / description
      Previous value: -"Relation-specific transformation note for DERIVED_FROM associations."New value: +"DERIVED_FROM only."
    • removedInput schema / properties / type / description
      Removed value: -"Relationship type between the two memories"
    • changedOutput schema / properties / created_count / description
      Previous value: -"Batch mode: number of associations created."New value: +"Batch mode."
    • changedOutput schema / properties / failed / description
      Previous value: -"Batch mode: failed association records with errors."New value: +"Batch mode."
    • changedOutput schema / properties / failed_count / description
      Previous value: -"Batch mode: number of associations that failed."New value: +"Batch mode."
    • removedOutput schema / properties / message / description
      Removed value: -"Confirmation message"
    • changedOutput schema / properties / succeeded / description
      Previous value: -"Batch mode: successful association records."New value: +"Batch mode."
    • changedOutput schema / properties / success / description
      Previous value: -"Whether every requested association was created. False for partial batch responses."New value: +"False when any batch item failed."
    • changedOutput schema / properties / summary / description
      Previous value: -"Batch mode: service summary."New value: +"Batch mode."
  2. Changed17 schema fields changedv0.14.1
    • addedInput schema / properties / associations
      Added value: +{
      +  "description": "Batch mode. Up to 500 associations. Do not combine with top-level memory1_id/memory2_id/type/strength.",
      +  "items": {
      +    "properties": {
      +      "confidence": {
      +        "description": "Relation-specific confidence for EXEMPLIFIES, EVOLVED_INTO, or DERIVED_FROM.",
      +        "maximum": 1,
      +        "minimum": 0,
      +        "type": "number"
      +      },
      +      "context": {
      +        "description": "Relation-specific context for PREFERS_OVER or PART_OF associations.",
      +        "type": "string"
      +      },
      +      "memory1_id": {
      +        "description": "ID of the source memory",
      +        "type": "string"
      +      },
      +      "memory2_id": {
      +        "description": "ID of the target memory",
      +        "type": "string"
      +      },
      +      "observations": {
      +        "description": "Relation-specific observations for REINFORCES associations.",
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      },
      +      "pattern_type": {
      +        "description": "Relation-specific pattern label for EXEMPLIFIES associations.",
      +        "type": "string"
      +      },
      +      "reason": {
      +        "description": "Relation-specific reason for PREFERS_OVER, CONTRADICTS, INVALIDATED_BY, or EVOLVED_INTO associations.",
      +        "type": "string"
      +      },
      +      "resolution": {
      +        "description": "Relation-specific resolution for CONTRADICTS associations.",
      +        "type": "string"
      +      },
      +      "role": {
      +        "description": "Relation-specific role for PART_OF associations.",
      +        "type": "string"
      +      },
      +      "strength": {
      +        "description": "Relationship strength from 0 to 1",
      +        "maximum": 1,
      +        "minimum": 0,
      +        "type": "number"
      +      },
      +      "timestamp": {
      +        "description": "Relation-specific timestamp for INVALIDATED_BY associations.",
      +        "type": "string"
      +      },
      +      "transformation": {
      +        "description": "Relation-specific transformation note for DERIVED_FROM associations.",
      +        "type": "string"
      +      },
      +      "type": {
      +        "description": "Relationship type between the two memories",
      +        "enum": [
      +          "RELATES_TO",
      +          "LEADS_TO",
      +          "OCCURRED_BEFORE",
      +          "PREFERS_OVER",
      +          "EXEMPLIFIES",
      +          "CONTRADICTS",
      +          "REINFORCES",
      +          "INVALIDATED_BY",
      +          "EVOLVED_INTO",
      +          "DERIVED_FROM",
      +          "PART_OF"
      +        ],
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "memory1_id",
      +      "memory2_id",
      +      "type",
      +      "strength"
      +    ],
      +    "type": "object"
      +  },
      +  "maxItems": 500,
      +  "minItems": 1,
      +  "type": "array"
      +}
    • addedInput schema / properties / confidence
      Added value: +{
      +  "description": "Relation-specific confidence for EXEMPLIFIES, EVOLVED_INTO, or DERIVED_FROM.",
      +  "maximum": 1,
      +  "minimum": 0,
      +  "type": "number"
      +}
    • addedInput schema / properties / context
      Added value: +{
      +  "description": "Relation-specific context for PREFERS_OVER or PART_OF associations.",
      +  "type": "string"
      +}
    • addedInput schema / properties / observations
      Added value: +{
      +  "description": "Relation-specific observations for REINFORCES associations.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / pattern_type
      Added value: +{
      +  "description": "Relation-specific pattern label for EXEMPLIFIES associations.",
      +  "type": "string"
      +}
    • addedInput schema / properties / reason
      Added value: +{
      +  "description": "Relation-specific reason for PREFERS_OVER, CONTRADICTS, INVALIDATED_BY, or EVOLVED_INTO associations.",
      +  "type": "string"
      +}
    • addedInput schema / properties / resolution
      Added value: +{
      +  "description": "Relation-specific resolution for CONTRADICTS associations.",
      +  "type": "string"
      +}
    • addedInput schema / properties / role
      Added value: +{
      +  "description": "Relation-specific role for PART_OF associations.",
      +  "type": "string"
      +}
    • addedInput schema / properties / timestamp
      Added value: +{
      +  "description": "Relation-specific timestamp for INVALIDATED_BY associations.",
      +  "type": "string"
      +}
    • addedInput schema / properties / transformation
      Added value: +{
      +  "description": "Relation-specific transformation note for DERIVED_FROM associations.",
      +  "type": "string"
      +}
    • removedInput schema / required
      Removed value: -[
      -  "memory1_id",
      -  "memory2_id",
      -  "type",
      -  "strength"
      -]
    • addedOutput schema / properties / created_count
      Added value: +{
      +  "description": "Batch mode: number of associations created.",
      +  "type": "integer"
      +}
    • addedOutput schema / properties / failed
      Added value: +{
      +  "description": "Batch mode: failed association records with errors.",
      +  "items": {
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • addedOutput schema / properties / failed_count
      Added value: +{
      +  "description": "Batch mode: number of associations that failed.",
      +  "type": "integer"
      +}
    • addedOutput schema / properties / succeeded
      Added value: +{
      +  "description": "Batch mode: successful association records.",
      +  "items": {
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • changedOutput schema / properties / success / description
      Previous value: -"Whether the association was created"New value: +"Whether every requested association was created. False for partial batch responses."
    • addedOutput schema / properties / summary
      Added value: +{
      +  "description": "Batch mode: service summary.",
      +  "type": "string"
      +}
  3. First observedv0.14.0

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already cover the write/idempotent/non-destructive profile, and the description adds genuinely new behavioral context: the graph-building rationale, the 500-item batch ceiling, and the critical distinction between authorable and read-only relation types. It does not state what happens when an identical association already exists or how failures in a batch are reported, which keeps it from a 5.

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?

Bold section headers front-load purpose, then usage, then relation taxonomy, then examples — easy to scan. The three worked examples are somewhat verbose and partly restate the schema, but they usefully demonstrate the batch shape, so they mostly earn their place.

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

Completeness4/5

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

For a 14-parameter tool with an output schema and annotations, the description covers mode selection, relation validity, and batching limits well. The one residual gap is error/partial-failure behavior in batch mode, but with an output schema present that is a reasonable omission.

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 93%, so baseline is 3, but the description earns extra credit by giving plain-language meaning to all eleven enum values (LEADS_TO as causation, INVALIDATED_BY as supersession, etc.), which the schema enum lists without explanation. The strength examples (0.9 bug-fix→feature, 0.8 old→new decision) further clarify intent.

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?

Opens with a specific verb and resource: 'Create typed relationships between memories,' and explains the downstream effect (knowledge graph improving recall). This clearly separates it from store_memory, recall_memory, and update_memory without needing their schemas.

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

Usage Guidelines5/5

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

A dedicated 'When to use' block lists four concrete triggering situations (after storing, bug-fix-to-feature, superseding decisions, pattern examples), and the description explicitly excludes system/internal relations like SIMILAR_TO as invalid inputs. Single-pair vs batch mode selection is also stated.

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