memory_relate

Instructions

Implementation Reference

• packages/mcp-server/src/tools/memory-relate.ts:1-37 (handler)

  The MCP tool handler for 'memory_relate'. Defines the schema with Zod (from_entity_id, to_entity_id, relationship_type, optional strength/context) and calls memoryEngine.relate() with the parameters.

  import { z } from 'zod'
  import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
  import type { MemoryEngine } from '../engine/memory-engine.js'
  
  export function registerMemoryRelate(server: McpServer, memoryEngine: MemoryEngine, agentId: string): void {
    server.tool(
      'memory_relate',
      'Create a relationship between two entities (e.g., "Amin" builds "ModQuote"). Relationships are bidirectional for querying but stored with a direction.',
      {
        from_entity_id: z.string().describe('Source entity ID'),
        to_entity_id: z.string().describe('Target entity ID'),
        relationship_type: z.string().describe('Type of relationship (e.g., "builds", "uses", "works_at", "prefers")'),
        strength: z.enum(['certain', 'high', 'medium', 'low']).optional(),
        context: z.string().optional().describe('What established this relationship'),
      },
      async (params) => {
        const result = await memoryEngine.relate({
          fromEntityId: params.from_entity_id,
          toEntityId: params.to_entity_id,
          relationshipType: params.relationship_type,
          agentId,
          strength: params.strength,
          context: params.context,
        })
  
        return {
          content: [{
            type: 'text' as const,
            text: JSON.stringify({
              relationship: result.relationship,
              receipt_id: result.receipt.receipt_id,
            }, null, 2),
          }],
        }
      },
    )
  }

• packages/mcp-server/src/tools/memory-relate.ts:9-15 (schema)

  Zod input schema for the memory_relate tool: from_entity_id, to_entity_id, relationship_type (required), strength (optional enum), context (optional string).

  {
    from_entity_id: z.string().describe('Source entity ID'),
    to_entity_id: z.string().describe('Target entity ID'),
    relationship_type: z.string().describe('Type of relationship (e.g., "builds", "uses", "works_at", "prefers")'),
    strength: z.enum(['certain', 'high', 'medium', 'low']).optional(),
    context: z.string().optional().describe('What established this relationship'),
  },

• packages/mcp-server/src/engine/memory-engine.ts:60-67 (schema)

  RelateParams interface used by the engine's relate() method. Contains fromEntityId, toEntityId, relationshipType, agentId, optional strength and context.

  export interface RelateParams {
    fromEntityId: string
    toEntityId: string
    relationshipType: string
    agentId: string
    strength?: ConfidenceLevel
    context?: string
  }

• packages/mcp-server/src/engine/memory-engine.ts:283-316 (helper)

  MemoryEngine.relate() method - the core logic. Creates a receipt via receiptEngine, then calls memoryStore.addRelationship() to persist the relationship, returning both the relationship and receipt.

  async relate(params: RelateParams): Promise<{ relationship: Relationship; receipt: ActionReceipt }> {
    const receipt = await this.receiptEngine.create({
      action: 'memory.relate',
      receipt_type: 'memory',
      input_hash: hashData({ from: params.fromEntityId, to: params.toEntityId, type: params.relationshipType }),
      status: 'completed',
      metadata: {
        memory: {
          memory_operation: 'observe',
          entity_id: params.fromEntityId,
          observation_id: null,
          relationship_id: null,
          scope: 'agent',
          query: null,
          results_count: null,
          confidence: params.strength ?? 'medium',
        },
      },
    })
  
    const relationship = this.memoryStore.addRelationship({
      relationship_id: `rel_${nanoid(12)}`,
      from_entity_id: params.fromEntityId,
      to_entity_id: params.toEntityId,
      relationship_type: params.relationshipType,
      strength: params.strength ?? 'medium',
      source_receipt_id: receipt.receipt_id,
      created_at: new Date().toISOString(),
      forgotten_at: null,
      metadata: params.context ? { context: params.context } : {},
    })
  
    return { relationship, receipt }
  }

• packages/mcp-server/src/tools/index.ts:23-23 (registration)

  Import of registerMemoryRelate from the memory-relate module.

  import { registerMemoryRelate } from './memory-relate.js'

• packages/mcp-server/src/tools/index.ts:58-58 (registration)

  Registration call for memory_relate tool within registerAllTools, only when memoryEngine, memoryStore, and agentId are all available.

  registerMemoryRelate(server, memoryEngine, agentId)