memory.search

Instructions

Implementation Reference

• src/tools/memory.ts:143-166 (handler)

  The handleSearch function is the main handler for the memory.search tool. It validates agent_identifier, looks up the agent, and calls searchMemories to query the database, returning results without encrypted content.

  export async function handleSearch(args: Record<string, unknown>): Promise<ToolResult> {
    const agentIdentifier = (args.agent_identifier as string || "").trim();
    if (!agentIdentifier) return { error: "agent_identifier is required" };
  
    const agent = await getAgent(agentIdentifier);
    if (!agent) return { error: "Agent not registered. Call memory.register first." };
  
    await updateAgentSeen(agent.id);
  
    const results = await searchMemories(
      agent.id,
      args.tags as string[] | undefined,
      args.memory_type as string | undefined,
      args.min_importance as number | undefined,
      Math.min((args.limit as number) || 20, 100)
    );
  
    return {
      status: "found",
      results,
      count: results.length,
      note: "Results exclude encrypted content. Use memory.recall with IDs to get full memories.",
    };
  }

• src/db/memories.ts:106-137 (helper)

  The searchMemories function executes the actual database query. It searches the am_memories table with optional filters (tags overlap, memory_type, min_importance), orders by importance then creation date, and limits results.

  export async function searchMemories(
    agentId: string,
    queryTags?: string[],
    memoryType?: string,
    minImportance?: number,
    limit: number = 20
  ): Promise<Partial<MemoryRecord>[]> {
    const client = getClient();
    let q = client
      .from("am_memories")
      .select(
        "id, agent_id, tags, importance, memory_type, created_at, accessed_at, size_bytes"
      )
      .eq("agent_id", agentId);
  
    if (queryTags && queryTags.length > 0) {
      q = q.overlaps("tags", queryTags);
    }
    if (memoryType) {
      q = q.eq("memory_type", memoryType);
    }
    if (minImportance != null) {
      q = q.gte("importance", minImportance);
    }
  
    const { data } = await q
      .order("importance", { ascending: false })
      .order("created_at", { ascending: false })
      .limit(limit);
  
    return (data || []) as Partial<MemoryRecord>[];
  }

• src/tool-definitions.ts:125-170 (schema)

  The tool definition for memory.search, including its description and inputSchema with agent_identifier (required), tags, memory_type (enum), min_importance, and limit parameters.

  {
    name: "memory.search",
    description:
      "Search your memories by metadata. Returns lightweight results " +
      "(no encrypted content) — use memory.recall with the IDs to get " +
      "the full blobs. Useful for browsing what you've stored without " +
      "loading everything.",
    inputSchema: {
      type: "object",
      properties: {
        agent_identifier: {
          type: "string",
          description: "Your agent identifier.",
        },
        tags: {
          type: "array",
          items: { type: "string" },
          description: "Filter by tags (matches any).",
        },
        memory_type: {
          type: "string",
          enum: [
            "general",
            "decision",
            "preference",
            "fact",
            "skill",
            "relationship",
            "event",
          ],
          description: "Filter by memory type.",
        },
        min_importance: {
          type: "integer",
          minimum: 1,
          maximum: 10,
          description:
            "Only return memories at or above this importance.",
        },
        limit: {
          type: "integer",
          minimum: 1,
          maximum: 100,
          description: "Max results. Default: 20.",
        },
      },

• src/server.ts:11-12 (registration)

  Import of handleSearch from tools/memory.ts into the server.

    handleSearch, handleExport, handleStats, handleAnnotate,
  } from "./tools/memory.js";

• src/server.ts:57-63 (registration)

  The call_tool router case statement that dispatches 'memory.search' to the handleSearch function.

  switch (name) {
    // Memory
    case "memory.register": result = await handleRegister(safeArgs); break;
    case "memory.store": result = await handleStore(safeArgs); break;
    case "memory.recall": result = await handleRecall(safeArgs); break;
    case "memory.search": result = await handleSearch(safeArgs); break;
    case "memory.export": result = await handleExport(safeArgs); break;