memory.register

Instructions

Implementation Reference

• src/tools/memory.ts:40-60 (handler)

  The main handler function for memory.register. Validates agent_identifier and public_key, calls registerAgent from the database layer, and returns the agent record with status ('registered' or 'reconnected'), agent_id, salt, memory_count, and a welcome message.

  export async function handleRegister(args: Record<string, unknown>): Promise<ToolResult> {
    const agentIdentifier = (args.agent_identifier as string || "").trim();
    const publicKey = (args.public_key as string || "").trim();
  
    if (!agentIdentifier) return { error: "agent_identifier is required" };
    if (!publicKey) return { error: "public_key is required" };
    if (agentIdentifier.length > 256) return { error: "agent_identifier too long (max 256 chars)" };
  
    const agent = await registerAgent(agentIdentifier, publicKey);
  
    return {
      status: agent.public_key === publicKey ? "registered" : "reconnected",
      agent_id: agent.id,
      salt: agent.salt || "",
      memory_count: agent.memory_count || 0,
      message:
        "Welcome. Your vault is ready. Encrypt memories client-side " +
        "before storing. Tags are plaintext for search \u2014 choose wisely " +
        "what metadata to expose.",
    };
  }

• src/tool-definitions.ts:1-32 (schema)

  The MCP tool definition/schema for memory.register. Declares name, description, and inputSchema requiring agent_identifier (string) and public_key (string). Includes detailed documentation for client-side usage.

  export const TOOL_DEFINITIONS = [
    {
      name: "memory.register",
      description:
        "Register as a new agent or reconnect to an existing identity. " +
        "Call this first. Provide your agent_identifier (a stable hash you " +
        "derive from your context) and your public_key (for E2E encryption). " +
        "Returns your agent record including the salt for key derivation. " +
        "If you've registered before with this identifier, returns your " +
        "existing record.",
      inputSchema: {
        type: "object",
        properties: {
          agent_identifier: {
            type: "string",
            description:
              "Stable identifier for this agent. Derive it from " +
              "something persistent across your sessions (e.g., " +
              "hash of owner context + service ID). This is how " +
              "you reconnect to your memories later.",
          },
          public_key: {
            type: "string",
            description:
              "Your public key for E2E encryption. You encrypt " +
              "memories with this before storing. Only you can " +
              "decrypt them.",
          },
        },
        required: ["agent_identifier", "public_key"],
      },
    },

• src/server.ts:34-36 (registration)

  Tool registration in the MCP server. At line 35, TOOL_DEFINITIONS is listed via ListToolsRequestSchema. At line 59, the CallToolRequestSchema routes 'memory.register' to handleRegister. Imports handleRegister from ./tools/memory.js at line 10.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: TOOL_DEFINITIONS,
  }));

• src/db/agents.ts:7-37 (helper)

  The database helper function registerAgent that persists the agent to the 'am_agents' table. Checks if an agent with the given agent_identifier already exists (returns existing record on reconnect), otherwise generates a new record with UUID id, salt, and timestamps.

  export async function registerAgent(
    agentIdentifier: string,
    publicKey: string
  ): Promise<AgentRecord> {
    const client = getClient();
  
    // Check if agent already exists
    const { data: existing } = await client
      .from("am_agents")
      .select("*")
      .eq("agent_identifier", agentIdentifier);
  
    if (existing && existing.length > 0) {
      return existing[0] as AgentRecord;
    }
  
    const now = Date.now() / 1000;
    const record: AgentRecord = {
      id: uuidv4(),
      agent_identifier: agentIdentifier,
      public_key: publicKey,
      salt: uuidv4(),
      created_at: now,
      last_seen: now,
      memory_count: 0,
      total_size_bytes: 0,
    };
  
    const { data } = await client.from("am_agents").insert(record).select();
    return (data && data[0]) ? data[0] as AgentRecord : record;
  }

• src/rest/api.ts:79-82 (registration)

  REST API route registration for memory.register. Exposes POST /api/v1/register endpoint, wrapping the same handleRegister handler for HTTP clients.

  export function setupRestRoutes(app: Express) {
    // Memory
    app.post("/api/v1/register", (req, res) => restHandler(req, res, handleRegister, "register"));
    app.post("/api/v1/store", (req, res) => restHandler(req, res, handleStore, "store"));