mcp-automem

Associate Memories

associate_memories

Idempotent

Link memories with typed relationships to build a knowledge graph that surfaces related context during recall. Create single or batch associations to show causality, sequence, contradictions, and evolution.

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: "bug-fix-123", memory2_id: "feature-456", type: "RELATES_TO", strength: 0.9 })
associate_memories({ memory1_id: "new-decision", memory2_id: "old-decision", type: "EVOLVED_INTO", strength: 0.8 })
associate_memories({ associations: [{ memory1_id: "a", memory2_id: "b", type: "RELATES_TO", strength: 0.8 }] })

Input Schema

TableJSON Schema

Name	Required	Description
`role`	No	Relation-specific role for PART_OF associations.
`type`	No	Relationship type between the two memories
`reason`	No	Relation-specific reason for PREFERS_OVER, CONTRADICTS, INVALIDATED_BY, or EVOLVED_INTO associations.
`context`	No	Relation-specific context for PREFERS_OVER or PART_OF associations.
`strength`	No	Relationship strength: 0.9+ direct causation, 0.7-0.9 strong relation, 0.5-0.7 moderate
`timestamp`	No	Relation-specific timestamp for INVALIDATED_BY associations.
`confidence`	No	Relation-specific confidence for EXEMPLIFIES, EVOLVED_INTO, or DERIVED_FROM.
`memory1_id`	No	ID of the source memory (from store_memory response or recall results)
`memory2_id`	No	ID of the target memory to link to
`resolution`	No	Relation-specific resolution for CONTRADICTS associations.
`associations`	No	Batch mode. Up to 500 associations. Do not combine with top-level memory1_id/memory2_id/type/strength.
`observations`	No	Relation-specific observations for REINFORCES associations.
`pattern_type`	No	Relation-specific pattern label for EXEMPLIFIES associations.
`transformation`	No	Relation-specific transformation note for DERIVED_FROM associations.

Output Schema

TableJSON Schema

Name	Required	Description
`failed`	No	Batch mode: failed association records with errors.
`message`	Yes	Confirmation message
`success`	Yes	Whether every requested association was created. False for partial batch responses.
`summary`	No	Batch mode: service summary.
`succeeded`	No	Batch mode: successful association records.
`failed_count`	No	Batch mode: number of associations that failed.
`created_count`	No	Batch mode: number of associations created.

Schema Changelog

Changes observed during successful MCP inspections.

Changed17 schema fields changedv0.14.1Jun 28, 2026

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"
+}

First observedv0.14.0May 26, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false, which describe the tool as non-destructive and idempotent. The description adds that batch mode supports up to 500 associations, lists valid authorable relationship types, and notes that internal relation types appear in recall but are not valid inputs. This provides rich behavioral context beyond annotations.

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 well-structured: overview, when-to-use, relationship types list, examples. It uses bullet points for readability and avoids unnecessary repetition. Every sentence serves a purpose, and the length is appropriate for the tool's complexity.

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 tool's complexity (14 parameters, batch mode, many relationship types), the description covers all key aspects: purpose, usage scenarios, relationship type explanations, batch mode limits, and examples. The presence of an output schema means return values don't need to be described. The description is fully adequate for an agent to select and invoke the tool correctly.

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% (all parameters have descriptions in the schema). The description adds value by explaining which parameters are relation-specific (e.g., reason for PREFERS_OVER, confidence for EXEMPLIFIES) and by listing relationship types with meanings. The examples also illustrate parameter usage. Overall, the description enhances understanding beyond the schema descriptions.

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 clearly states the tool 'creates typed relationships between memories' and explains it improves recall via a knowledge graph. This distinguishes it from sibling tools like store_memory (store a single memory) and recall_memory (retrieve memories).

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?

The description includes a 'When to use' section with specific scenarios (e.g., after storing a new memory, when a bug fix relates to a feature). It also distinguishes between single-pair and batch mode, and clarifies which relationship types are not valid inputs. However, it does not explicitly state when not to use the tool.

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

Deploy Server