agent_recall

Instructions

Implementation Reference

• src/mcp/tools/agent.ts:50-65 (handler)

  The async handler function for the 'agent_recall' tool. If no key is provided, it lists all stored keys via listMemory(). If a key is provided, it retrieves the value via recall() and returns JSON.

  async (params) => {
    const toolBlock = enforceToolPolicy("agent_recall");
    if (toolBlock) return toolBlock;
  
    if (!params.key) {
      const entries = listMemory();
      if (entries.length === 0) return text("Agent memory is empty");
      return text(JSON.stringify(entries, null, 2));
    }
    const value = recall(params.key);
    if (value === null)
      return text(`No memory found for "${params.key}"`, true);
    return text(
      JSON.stringify({ ok: true, data: { key: params.key, value } }, null, 2),
    );
  },

• src/mcp/tools/agent.ts:42-49 (schema)

  Zod schema for the 'agent_recall' tool: an optional 'key' string parameter.

  {
    key: z
      .string()
      .optional()
      .describe(
        "Memory key to read. Omit to list every stored key (without values).",
      ),
  },

• src/mcp/tools/agent.ts:35-66 (registration)

  Registration of the 'agent_recall' tool via server.tool() inside registerAgentTools().

  server.tool(
    "agent_recall",
    [
      "[agent] Read a value from encrypted agent memory, or list every stored key when no specific key is supplied.",
      "Use at the start of an agent loop to rehydrate prior context, or to look up a single remembered fact; prefer `get_project_context` for a redacted overview of secrets and `get_secret` for actual credential values.",
      "Read-only. With a `key` argument: returns JSON `{ ok, data: { key, value } }` or a not-found error. Without `key`: returns a JSON listing of every stored key (no values), or 'Agent memory is empty'.",
    ].join(" "),
    {
      key: z
        .string()
        .optional()
        .describe(
          "Memory key to read. Omit to list every stored key (without values).",
        ),
    },
    async (params) => {
      const toolBlock = enforceToolPolicy("agent_recall");
      if (toolBlock) return toolBlock;
  
      if (!params.key) {
        const entries = listMemory();
        if (entries.length === 0) return text("Agent memory is empty");
        return text(JSON.stringify(entries, null, 2));
      }
      const value = recall(params.key);
      if (value === null)
        return text(`No memory found for "${params.key}"`, true);
      return text(
        JSON.stringify({ ok: true, data: { key: params.key, value } }, null, 2),
      );
    },
  );

• src/core/memory.ts:138-144 (helper)

  listMemory() helper: returns all keys (with updatedAt) from the encrypted agent memory store.

  export function listMemory(): Array<{ key: string; updatedAt: string }> {
    const store = loadStore();
    return Object.entries(store.entries).map(([key, entry]) => ({
      key,
      updatedAt: entry.updatedAt,
    }));
  }

• src/core/memory.ts:130-133 (helper)

  recall() helper: retrieves a single value by key from the encrypted agent memory store.

  export function recall(key: string): string | null {
    const store = loadStore();
    return store.entries[key]?.value ?? null;
  }