create_relations

Define and establish relationships between entities in a knowledge graph. Specify source, target, and relation type to actively build structured connections for enhanced reasoning and problem-solving.

Instructions

Create multiple new relations between entities in the knowledge graph. Relations should be in active voice

Input Schema

TableJSON Schema

Name	Required	Description	Default
`relations`	Yes	Array of relations to create

Implementation Reference

src/memory/tools.ts:165-201 (handler)

The core execute function for the 'create_relations' tool. It processes an array of relations, attempts to add each to the graph using graph.addRelation, checks for existence of source/target entities or duplicate relations for failures, collects results, saves the memory store, and returns a JSON string with created/failed counts and details.

execute: async (args) => {
  const results = {
    created: [] as Array<{from: string, to: string, relationType: string}>,
    failed: [] as Array<{from: string, to: string, relationType: string, reason: string}>
  };

  // Using the lower-level graph for relations for now
  // In a future update, we can add relation handling to the MemoryStore itself
  for (const relation of args.relations) {
    const success = graph.addRelation(relation);
    if (success) {
      results.created.push(relation);
    } else {
      // Determine failure reason
      let reason = "Unknown error";
      if (!graph.entities.has(relation.from)) {
        reason = `Source entity '${relation.from}' doesn't exist`;
      } else if (!graph.entities.has(relation.to)) {
        reason = `Target entity '${relation.to}' doesn't exist`;
      } else {
        reason = "Relation already exists";
      }
      
      results.failed.push({...relation, reason});
    }
  }

  // Save changes
  await memoryStore.save();

  // Return as string
  return JSON.stringify({
    created: results.created.length > 0 ? results.created : null,
    failed: results.failed.length > 0 ? results.failed : null,
    message: `Created ${results.created.length} new relations. ${results.failed.length} relations failed.`
  });
}

src/utils/validation.ts:30-32 (schema)
Zod schema defining the input parameters for the create_relations tool: an array of relations.
```
export const CreateRelationsSchema = z.object({
  relations: z.array(RelationSchema).describe('Array of relations to create')
});
```

src/memory/tools.ts:161-202 (registration)

Registers the 'create_relations' tool on the FastMCP server with name, description, schema, and inline execute handler.

server.addTool({
  name: 'create_relations',
  description: 'Create multiple new relations between entities in the knowledge graph. Relations should be in active voice',
  parameters: Schemas.CreateRelationsSchema,
  execute: async (args) => {
    const results = {
      created: [] as Array<{from: string, to: string, relationType: string}>,
      failed: [] as Array<{from: string, to: string, relationType: string, reason: string}>
    };

    // Using the lower-level graph for relations for now
    // In a future update, we can add relation handling to the MemoryStore itself
    for (const relation of args.relations) {
      const success = graph.addRelation(relation);
      if (success) {
        results.created.push(relation);
      } else {
        // Determine failure reason
        let reason = "Unknown error";
        if (!graph.entities.has(relation.from)) {
          reason = `Source entity '${relation.from}' doesn't exist`;
        } else if (!graph.entities.has(relation.to)) {
          reason = `Target entity '${relation.to}' doesn't exist`;
        } else {
          reason = "Relation already exists";
        }
        
        results.failed.push({...relation, reason});
      }
    }

    // Save changes
    await memoryStore.save();

    // Return as string
    return JSON.stringify({
      created: results.created.length > 0 ? results.created : null,
      failed: results.failed.length > 0 ? results.failed : null,
      message: `Created ${results.created.length} new relations. ${results.failed.length} relations failed.`
    });
  }
});

src/core/tools.ts:15-16 (registration)
Invokes registerMemoryTools(server) as part of registering all tools, which includes the create_relations tool.
```
console.error('[INFO] [tools] Registering memory tools...');
registerMemoryTools(server);
```

src/utils/validation.ts:12-16 (helper)

Zod schema for individual relation objects used in CreateRelationsSchema.

const RelationSchema = z.object({
  from: z.string().min(1).describe('Source entity name'),
  to: z.string().min(1).describe('Target entity name'),
  relationType: z.string().min(1).describe('Type of relationship (in active voice)')
});

MCP Think Tank