aim_memory_link

Instructions

Implementation Reference

• index.ts:454-499 (schema)

  Tool registration and input schema for aim_memory_link — defines name, description, and inputSchema with context, location, and relations fields.

        {
          name: "aim_memory_link",
          description: `Link two memories together with a relationship. Use this to connect related information.
  
  RELATION STRUCTURE: Each link has 'from' (subject), 'relationType' (verb), and 'to' (object).
  - Use active voice verbs: "manages", "works_at", "knows", "attended", "created"
  - Read as: "from relationType to" (e.g., "Alice manages Q4_Project")
  - Avoid passive: use "manages" not "is_managed_by"
  
  IMPORTANT: Both 'from' and 'to' entities must already exist in the same database.
  
  RETURNS: Array of created relations (duplicates are ignored).
  
  DATABASE: Relations are created in the specified 'context' database, or master database if not specified.
  
  EXAMPLES:
  - aim_memory_link({relations: [{from: "John", to: "TechConf2024", relationType: "attended"}]})
  - aim_memory_link({context: "work", relations: [{from: "Alice", to: "Q4_Project", relationType: "manages"}]})
  - Multiple: aim_memory_link({relations: [{from: "John", to: "Alice", relationType: "knows"}, {from: "John", to: "Acme_Corp", relationType: "works_at"}]})`,
          inputSchema: {
            type: "object",
            properties: {
              context: {
                type: "string",
                description: "Optional memory context. Relations will be created in the specified context's knowledge graph."
              },
              location: {
                type: "string",
                enum: ["project", "global"],
                description: "Optional storage location override. 'project' forces project-local .aim directory, 'global' forces global directory. If not specified, uses automatic detection."
              },
              relations: {
                type: "array",
                items: {
                  type: "object",
                  properties: {
                    from: { type: "string", description: "The name of the entity where the relation starts" },
                    to: { type: "string", description: "The name of the entity where the relation ends" },
                    relationType: { type: "string", description: "The type of the relation" },
                  },
                  required: ["from", "to", "relationType"],
                },
              },
            },
            required: ["relations"],
          },

• index.ts:818-819 (handler)

  Handler for aim_memory_link — calls knowledgeGraphManager.createRelations() with args.relations, args.context, and args.location.

  case "aim_memory_link":
    return { content: [{ type: "text", text: JSON.stringify(await knowledgeGraphManager.createRelations(args.relations as Relation[], args.context as string, args.location as 'project' | 'global'), null, 2) }] };

• index.ts:227-237 (helper)

  createRelations method in KnowledgeGraphManager — loads the graph, filters out duplicates, adds new relations, saves and returns them.

  async createRelations(relations: Relation[], context?: string, location?: 'project' | 'global'): Promise<Relation[]> {
    const graph = await this.loadGraph(context, location);
    const newRelations = relations.filter(r => !graph.relations.some(existingRelation =>
      existingRelation.from === r.from &&
      existingRelation.to === r.to &&
      existingRelation.relationType === r.relationType
    ));
    graph.relations.push(...newRelations);
    await this.saveGraph(graph, context, location);
    return newRelations;
  }

• index.ts:120-124 (helper)

  Relation interface — defines the structure of a relation with from, to, and relationType fields.

  interface Relation {
    from: string;
    to: string;
    relationType: string;
  }