mcp-automem

Associate Memories

associate_memories

Idempotent

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).

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 }] })

Input 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

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.6/5.0

Behavior4/5

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

Annotations already disclose non-readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds real context beyond that: the 500-item batch cap and the mutual-exclusion rule that associations[] must not be combined with top-level memory1_id/memory2_id/type/strength. It stops short of saying what happens on unknown memory IDs or directionality semantics beyond the examples.

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 one-sentence purpose, then clearly headed sections for when-to-use, type semantics, and examples. The type list and examples are long but each earns its place; the three near-identical examples with full UUIDs are somewhat repetitive and could be trimmed to one pair plus one batch call.

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?

For a 14-parameter mutation tool with an output schema and annotations present, the description covers the remaining gaps: mode selection, batch limit, mutual exclusion, valid vs invalid relation types, and strength intuition. Return values need not be explained since an output schema exists, so nothing essential is missing.

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 would be 3; the description earns an upgrade because the schema lists the type enum without per-value meaning, and the description defines all eleven authorable relationship types with examples (LEADS_TO = causal, INVALIDATED_BY = superseded, etc.). The worked examples also show strength values in context (0.9, 0.8).

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?

States a specific verb and resource ('Create typed relationships between memories') and immediately names the value proposition (knowledge graph improving recall). It also distinguishes the two invocation shapes, single-pair vs batch via associations[], so an agent knows the tool's full surface without opening the schema.

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?

An explicit 'When to use' block gives four concrete triggering scenarios (after store_memory, bug fix vs feature, superseding decisions, pattern/example pairing). It also gives an explicit when-NOT: system relations such as SIMILAR_TO and DISCOVERED may show up in recall but are not valid inputs here, which prevents a plausible failure mode.

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

Deploy Server