aim_memory_search

Instructions

Implementation Reference

• index.ts:838-843 (handler)

  The tool handler for aim_memory_search in the CallToolRequestSchema switch statement. Calls knowledgeGraphManager.searchNodes() and formats output as JSON or pretty text.

  case "aim_memory_search": {
    const graph = await knowledgeGraphManager.searchNodes(args.query as string, args.context as string, args.location as 'project' | 'global');
    const output = args.format === 'pretty'
      ? formatGraphPretty(graph, args.context as string)
      : JSON.stringify(graph, null, 2);
    return { content: [{ type: "text", text: output }] };

• index.ts:718-738 (schema)

  Input schema for aim_memory_search defining properties: context (optional database name), location (project/global), query (search text), and format (json/pretty). 'query' is required.

  inputSchema: {
    type: "object",
    properties: {
      context: {
        type: "string",
        description: "Optional database name. Searches within this database or master database if not specified."
      },
      location: {
        type: "string",
        enum: ["project", "global"],
        description: "Optional storage location override. 'project' for .aim directory, 'global' for configured directory."
      },
      query: { type: "string", description: "Search text to match against entity names, entity types, and observation content (case-insensitive)" },
      format: {
        type: "string",
        enum: ["json", "pretty"],
        description: "Output format. 'json' (default) for structured data, 'pretty' for human-readable text."
      }
    },
    required: ["query"],
  },

• index.ts:287-311 (helper)

  The searchNodes method in KnowledgeGraphManager. Loads the graph, filters entities by case-insensitive matching against name, entityType, and observations, then returns a filtered graph with only relations between matched entities.

  async searchNodes(query: string, context?: string, location?: 'project' | 'global'): Promise<KnowledgeGraph> {
    const graph = await this.loadGraph(context, location);
  
    // Filter entities
    const filteredEntities = graph.entities.filter(e =>
      e.name.toLowerCase().includes(query.toLowerCase()) ||
      e.entityType.toLowerCase().includes(query.toLowerCase()) ||
      e.observations.some(o => o.toLowerCase().includes(query.toLowerCase()))
    );
  
    // Create a Set of filtered entity names for quick lookup
    const filteredEntityNames = new Set(filteredEntities.map(e => e.name));
  
    // Filter relations to only include those between filtered entities
    const filteredRelations = graph.relations.filter(r =>
      filteredEntityNames.has(r.from) && filteredEntityNames.has(r.to)
    );
  
    const filteredGraph: KnowledgeGraph = {
      entities: filteredEntities,
      relations: filteredRelations,
    };
  
    return filteredGraph;
  }

• index.ts:699-739 (registration)

  Tool registration in the ListToolsRequestSchema handler. Defines the tool name 'aim_memory_search' with its description and input schema.

        {
          name: "aim_memory_search",
          description: `Search memories by keyword. Use this when you don't know the exact name of what you're looking for.
  
  WHAT IT SEARCHES: Matches query (case-insensitive) against:
  - Memory names (e.g., "John" matches "John_Smith")
  - Memory types (e.g., "person" matches all person memories)
  - Facts/observations (e.g., "Seattle" matches memories mentioning Seattle)
  
  VS aim_memory_get: Use aim_memory_search for fuzzy matching. Use aim_memory_get when you know exact names.
  
  FORMAT OPTIONS:
  - "json" (default): Structured JSON for programmatic use
  - "pretty": Human-readable text format
  
  EXAMPLES:
  - aim_memory_search({query: "John"}) - JSON format
  - aim_memory_search({query: "project", format: "pretty"}) - Human-readable
  - aim_memory_search({context: "work", query: "Shane", format: "pretty"})`,
          inputSchema: {
            type: "object",
            properties: {
              context: {
                type: "string",
                description: "Optional database name. Searches within this database or master database if not specified."
              },
              location: {
                type: "string",
                enum: ["project", "global"],
                description: "Optional storage location override. 'project' for .aim directory, 'global' for configured directory."
              },
              query: { type: "string", description: "Search text to match against entity names, entity types, and observation content (case-insensitive)" },
              format: {
                type: "string",
                enum: ["json", "pretty"],
                description: "Output format. 'json' (default) for structured data, 'pretty' for human-readable text."
              }
            },
            required: ["query"],
          },
        },