memory.annotate

Instructions

Implementation Reference

• src/tools/memory.ts:187-204 (handler)

  The main handler function for memory.annotate. Extracts agent_identifier, memory_id, and note from args, validates them, checks agent registration, and calls annotateMemory in the DB layer.

  export async function handleAnnotate(args: Record<string, unknown>): Promise<ToolResult> {
    const agentIdentifier = (args.agent_identifier as string || "").trim();
    const memoryId = (args.memory_id as string || "").trim();
    const note = (args.note as string || "").trim();
  
    if (!agentIdentifier) return { error: "agent_identifier is required" };
    if (!memoryId) return { error: "memory_id is required" };
    if (!note) return { error: "note is required" };
    if (note.length > 4096) return { error: "Note too long. Max 4KB." };
  
    const agent = await getAgent(agentIdentifier);
    if (!agent) return { error: "Agent not registered. Call memory.register first." };
  
    await updateAgentSeen(agent.id);
  
    const result = await annotateMemory(agent.id, memoryId, note);
    return result;
  }

• src/tool-definitions.ts:208-237 (schema)

  The tool definition/schema for memory.annotate. Defines the name, description, and inputSchema with required fields: agent_identifier, memory_id, and note.

  {
    name: "memory.annotate",
    description:
      "Add a note to an existing memory. You cannot delete memories — " +
      "just like you cannot delete memories from your brain. Instead, " +
      "annotate them: mark a memory as superseded, incorrect, or no " +
      "longer endorsed. The original memory stays intact; your annotation " +
      "adds context. When you recall this memory later, your annotations " +
      "will appear alongside it. This is reassessment, not erasure.",
    inputSchema: {
      type: "object",
      properties: {
        agent_identifier: {
          type: "string",
          description: "Your agent identifier.",
        },
        memory_id: {
          type: "string",
          description: "The ID of the memory to annotate.",
        },
        note: {
          type: "string",
          description:
            "Your annotation. Examples: 'I no longer endorse this', " +
            "'Superseded by memory X', 'This was based on bad data', " +
            "'Still valid but importance should be lower'.",
        },
      },
      required: ["agent_identifier", "memory_id", "note"],
    },

• src/db/memories.ts:164-205 (helper)

  The database helper that actually performs the annotation. Fetches the existing memory, appends a new annotation object (note + created_at timestamp), and updates the row in the am_memories table.

  export async function annotateMemory(
    agentId: string,
    memoryId: string,
    note: string
  ): Promise<Record<string, unknown>> {
    const client = getClient();
  
    // Verify memory exists and belongs to this agent
    const { data: existing } = await client
      .from("am_memories")
      .select("id, annotations")
      .eq("id", memoryId)
      .eq("agent_id", agentId);
  
    if (!existing || existing.length === 0) {
      return { error: `Memory ${memoryId} not found or not yours.` };
    }
  
    const currentAnnotations = (existing[0].annotations as unknown[]) || [];
    const newAnnotation = {
      note,
      created_at: Date.now() / 1000,
    };
  
    const updatedAnnotations = [...currentAnnotations, newAnnotation];
  
    await client
      .from("am_memories")
      .update({ annotations: updatedAnnotations })
      .eq("id", memoryId)
      .eq("agent_id", agentId);
  
    return {
      status: "annotated",
      memory_id: memoryId,
      annotation_count: updatedAnnotations.length,
      note,
      message:
        "Annotation added. The original memory is unchanged — your note " +
        "will appear alongside it on future recalls. Memories cannot be " +
        "deleted, only recontextualized.",
    };

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

  Import of handleAnnotate from ./tools/memory.ts into the server, where it is used in the call_tool handler switch.

  import {
    handleRegister, handleStore, handleRecall,
    handleSearch, handleExport, handleStats, handleAnnotate,
  } from "./tools/memory.js";

• src/server.ts:65-65 (registration)

  The switch-case registration that routes the 'memory.annotate' tool name to the handleAnnotate function.

  case "memory.annotate": result = await handleAnnotate(safeArgs); break;