aim_memory_add_facts

Instructions

Implementation Reference

• index.ts:501-543 (registration)

  Tool registration for 'aim_memory_add_facts' in the ListToolsRequestSchema handler. Defines name, description, and inputSchema (accepts context, location, observations).

        {
          name: "aim_memory_add_facts",
          description: `Add new facts to an existing memory. Use this to append information to something already stored.
  
  IMPORTANT: Memory must already exist - use aim_memory_store first. Throws error if not found.
  
  RETURNS: Array of {entityName, addedObservations} showing what was added (duplicates are ignored).
  
  DATABASE: Adds to entities in the specified 'context' database, or master database if not specified.
  
  EXAMPLES:
  - aim_memory_add_facts({observations: [{entityName: "John", contents: ["Lives in Seattle", "Works in tech"]}]})
  - aim_memory_add_facts({context: "work", observations: [{entityName: "Q4_Project", contents: ["Behind schedule", "Need more resources"]}]})`,
          inputSchema: {
            type: "object",
            properties: {
              context: {
                type: "string",
                description: "Optional memory context. Observations will be added to entities 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."
              },
              observations: {
                type: "array",
                items: {
                  type: "object",
                  properties: {
                    entityName: { type: "string", description: "The name of the entity to add the observations to" },
                    contents: {
                      type: "array",
                      items: { type: "string" },
                      description: "An array of observation contents to add"
                    },
                  },
                  required: ["entityName", "contents"],
                },
              },
            },
            required: ["observations"],
          },

• index.ts:820-821 (handler)

  The CallToolRequestSchema handler case for 'aim_memory_add_facts'. Calls knowledgeGraphManager.addObservations() with the args and returns JSON result.

  case "aim_memory_add_facts":
    return { content: [{ type: "text", text: JSON.stringify(await knowledgeGraphManager.addObservations(args.observations as { entityName: string; contents: string[] }[], args.context as string, args.location as 'project' | 'global'), null, 2) }] };

• index.ts:239-252 (helper)

  The addObservations method on KnowledgeGraphManager. Loads the graph, finds each entity by name (throws if not found), filters out duplicate observations, adds new ones, saves, and returns results.

  async addObservations(observations: { entityName: string; contents: string[] }[], context?: string, location?: 'project' | 'global'): Promise<{ entityName: string; addedObservations: string[] }[]> {
    const graph = await this.loadGraph(context, location);
    const results = observations.map(o => {
      const entity = graph.entities.find(e => e.name === o.entityName);
      if (!entity) {
        throw new Error(`Entity with name ${o.entityName} not found`);
      }
      const newObservations = o.contents.filter(content => !entity.observations.includes(content));
      entity.observations.push(...newObservations);
      return { entityName: o.entityName, addedObservations: newObservations };
    });
    await this.saveGraph(graph, context, location);
    return results;
  }

• index.ts:514-542 (schema)

  Input schema for aim_memory_add_facts: requires 'observations' array of {entityName, contents[]}, optional 'context' string and 'location' enum.

  inputSchema: {
    type: "object",
    properties: {
      context: {
        type: "string",
        description: "Optional memory context. Observations will be added to entities 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."
      },
      observations: {
        type: "array",
        items: {
          type: "object",
          properties: {
            entityName: { type: "string", description: "The name of the entity to add the observations to" },
            contents: {
              type: "array",
              items: { type: "string" },
              description: "An array of observation contents to add"
            },
          },
          required: ["entityName", "contents"],
        },
      },
    },
    required: ["observations"],