Prism MCP

Instructions

Implementation Reference

• src/tools/sessionMemoryHandlers.ts:1606-1675 (handler)

  The handler for the session_forget_memory MCP tool. It validates input, accesses storage, and handles either soft (tombstone) or hard deletion of memory entries.

  export async function sessionForgetMemoryHandler(args: unknown) {
    try {
      // ─── Input Validation ───
      if (!isSessionForgetMemoryArgs(args)) {
        return {
          content: [{
            type: "text",
            text: "Invalid arguments. Required: memory_id (string). Optional: hard_delete (boolean), reason (string).",
          }],
          isError: true,
        };
      }
  
      const { memory_id, hard_delete = false, reason } = args;
  
      // ─── Get Storage Backend ───
      const storage = await getStorage();
  
      // ─── Execute Deletion ───
      // The storage methods verify user_id ownership internally,
      // preventing cross-user deletion attacks.
      if (hard_delete) {
        // IRREVERSIBLE: Physical removal from the database.
        // FTS5 triggers (SQLite) or Supabase cascades clean up indexes.
        await storage.hardDeleteLedger(memory_id, PRISM_USER_ID);
  
        debugLog(`[session_forget_memory] Hard-deleted entry ${memory_id}`);
  
        return {
          content: [{
            type: "text",
            text: `🗑️ **Hard Deleted** memory entry \`${memory_id}\`.\n\n` +
              `This entry has been permanently removed from the database. ` +
              `It cannot be recovered. All associated embeddings and FTS indexes ` +
              `have been cleaned up.`,
          }],
          isError: false,
        };
      } else {
        // REVERSIBLE: Soft-delete (tombstone) — sets deleted_at + deleted_reason.
        // The entry remains in the database but is excluded from ALL search
        // queries (vector, FTS5, and context loading).
        await storage.softDeleteLedger(memory_id, PRISM_USER_ID, reason);
  
        debugLog(`[session_forget_memory] Soft-deleted entry ${memory_id} (reason: ${reason || "none"})`);
  
        return {
          content: [{
            type: "text",
            text: `🔇 **Soft Deleted** memory entry \`${memory_id}\`.\n\n` +
              `The entry has been tombstoned (deleted_at = NOW()). ` +
              `It will no longer appear in any search results, but remains ` +
              `in the database for audit trail purposes.\n\n` +
              (reason ? `📋 **Reason**: ${reason}\n\n` : "") +
              `To permanently remove this entry, call again with \`hard_delete: true\`.`,
          }],
          isError: false,
        };
      }
    } catch (error) {
      console.error(`[session_forget_memory] Error: ${error}`);
      return {
        content: [{
          type: "text",
          text: `Error forgetting memory: ${error instanceof Error ? error.message : String(error)}`,
        }],
        isError: true,
      };
    }
  }

• src/tools/sessionMemoryDefinitions.ts:679-733 (schema)

  Tool definition and type guard for session_forget_memory.

  export const SESSION_FORGET_MEMORY_TOOL: Tool = {
    name: "session_forget_memory",
    description:
      "Forget (delete) a specific memory entry by its ID. " +
      "Supports two modes:\n\n" +
      "- **Soft delete** (default): Tombstones the entry — it stays in the database " +
      "for audit trails but is excluded from all search results. Reversible.\n" +
      "- **Hard delete**: Permanently removes the entry from the database. Irreversible. " +
      "Use only when GDPR Article 17 requires complete erasure.\n\n" +
      "⚠️ Soft delete is recommended for most use cases. The entry can be " +
      "restored in the future if needed.",
    inputSchema: {
      type: "object",
      properties: {
        memory_id: {
          type: "string",
          description:
            "The UUID of the memory (ledger) entry to forget. " +
            "You can find this ID in search results returned by " +
            "session_search_memory or knowledge_search.",
        },
        hard_delete: {
          type: "boolean",
          description:
            "If true, permanently removes the entry (irreversible). " +
            "If false (default), soft-deletes by setting deleted_at timestamp. " +
            "Soft-deleted entries are excluded from searches but remain in the database.",
        },
        reason: {
          type: "string",
          description:
            "Optional GDPR Article 17 justification for the deletion. " +
            "Examples: 'User requested', 'Data retention policy', 'Outdated information'. " +
            "Stored alongside the tombstone for audit trail purposes.",
        },
      },
      required: ["memory_id"],
    },
  };
  
  /**
   * Type guard for session_forget_memory arguments.
   * Validates that memory_id (required) is present and is a string.
   * hard_delete and reason are optional.
   */
  export function isSessionForgetMemoryArgs(
    args: unknown
  ): args is { memory_id: string; hard_delete?: boolean; reason?: string } {
    return (
      typeof args === "object" &&
      args !== null &&
      "memory_id" in args &&
      typeof (args as { memory_id: string }).memory_id === "string"
    );
  }

• src/server.ts:590-592 (registration)

  Tool handler registration in the MCP server.

  case "session_forget_memory":
    if (!SESSION_MEMORY_ENABLED) throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
    return await sessionForgetMemoryHandler(args);